ycd / toc Goto Github PK

When you generate a ToC skipping a level the generated ToC keeps the indentation for the bullet as the skipped headers would be there producing a wrong rendering in GH.

Example

Original Markdown file (example.md):

# Header 1

<!-- toc -->

## Header 2.1

## Header 2.2

### Header 2.2.3.1

### Header 2.2.3.2

Result of executing toc -p example.md:

# Header 1

<!-- toc -->
- [Header 1](#header-1)
    * [Header 2.1](#header-21)
    * [Header 2.2](#header-22)
        * [Header 2.2.3.1](#header-2231)
        * [Header 2.2.3.2](#header-2232)

<!-- tocstop -->

## Header 2.1

## Header 2.2

### Header 2.2.3.1

### Header 2.2.3.2

It's rendered as

Result of executing toc -p example.md -s 1:

# Header 1

<!-- toc -->
    * [Header 2.1](#header-21)
    * [Header 2.2](#header-22)
        * [Header 2.2.3.1](#header-2231)
        * [Header 2.2.3.2](#header-2232)

<!-- tocstop -->

## Header 2.1

## Header 2.2

### Header 2.2.3.1

### Header 2.2.3.2

It's rendered as

Don’t write status messages to stdout.

• Currently using pipes with --append=false writes

   ~$ toc -p <(curl https://raw.githubusercontent.com/ycd/toc/main/README.md 2>&-) --append=false > toc.md
   ~$ cat toc.md

    - [Table of Contents](#table-of-contents)
        * [Usage](#usage)
        * [Installation](#installation)
            * [Packages](#packages)
            * [Downloads](#downloads)
            * [Installation from source](#installation-from-source)
                * [Unix/Linux](#unixlinux)
        * [Contributing](#contributing)
        * [Licence](#licence)
    ✔ Table of contents generated successfully.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ <- This shouldn't be included

It would be helpful if toc was available as a docker image. I think a simple scratch container with a static binary in it would be sufficient.

I'd offer a PR to your goreleaser.yaml but I can't really test it and don't know which docker registry you would prefer.

Looking over go.mod its currently set to toc. This should be changed to github.com/ycd/toc so this tool can be installed using:

$ go install github.com/ycd/toc

It currently fails with this:

go install: github.com/ycd/toc@latest: github.com/ycd/[email protected]: parsing go.mod:
	module declares its path as: toc
	        but was required as: github.com/ycd/toc

Add support for specifying skip option for first n header.

-s <int>
--skip <int>

Using the --skip 1 flag for the markdown file below should preserve this output:

Markdown file:

# Test

# Actual header

# Actual header two

Expected output

- [Actual header](#actual-header)
- [Actual header two](#actual-header-two)

Used this and found a small bug only relevant to headings containing _.

This is the current output:

- [ISSUE_TEMPLATE.md](#issue-templatemd)
- [PULL_REQUEST_TEMPLATE.md](#pull-request-templatemd)

These are the ones github uses for its links:

- [ISSUE_TEMPLATE.md](#issue_templatemd)
- [PULL_REQUEST_TEMPLATE.md](#pull_request_templatemd)

Or is there another standard which GitHub does not comply to?

Add support for specifying nested header depth.

-d <int>
--depth <int>

• For example include only include maximum till h2

toc -p /path/to/markdown -d 2

Capture the table of contents like in a syntax like this

<!--start toc-->  
Table of contents
<!--end toc-->  

$ git clone https://github.com/ycd/toc 
$ cd ycd

should say

$ git clone https://github.com/ycd/toc 
$ cd toc

because git clones to a directory called "toc".

Likewise

# May require you to use sudo
$ go build .
$ cp toc /usr/local/toc

should say

$ go build .
# May require you to use sudo
$ cp toc /usr/local/bin

because the go build . step writes to a place that the user can write to, but "/usr/local/bin" is not where a user can usually write to. "/usr/local" isn't in most people's $PATH but "/usr/local/bin" is.