kevingimbel/mktoc

🦀 Markdown Table of Content generator

mktoc's Issues

Proper documentation

Actually write down how to use mktoc.

Strip special characters

Special characters like ( must be removed from the link.

The headline

## MongoDB (Atlas)

must be linked as

- [MongoDB (Atlas)](#mongodb-atlas)

but currently mktoc produces a link like

- [MongoDB (Atlas)](#mongodb-(atlas))

Feature: wrap ToC in details block

Add an option to wrap the generated ToC in a <details> element.

Example:

Table of Contents

• Installation 🤖
  • Build from source
    • Prerequisites
    • Instructions
  • Binary releases
  • Docker
    • Images
    • Usage
    • Building

Code:

<!-- BEGIN mktoc -->
<details>
  <summary>Table of Contents</summary>

- [Installation 🤖](#installation)
  - [Build from source](#build-from-source)
    - [Prerequisites](#prerequisites)
    - [Instructions](#instructions)
  - [Binary releases](#binary-releases)
  - [Docker](#docker)
    - [Images](#images)
    - [Usage](#usage)
    - [Building](#building)
</details>
<!-- END mktoc -->

Important:

• Newline after <summary> is required, otherwise the markdown is not parsed.
• Should be configurable via ENV, cli argument, and inline config

Automate binary releases

Find a way how binaries can be released and added to GitHub Releases.

Parsing issues

Since we're using a "simple" Regex based parser to find headlines we also get things that are not a headline, e.g. comment blocks inside of code snippets:

# my comment
pub fn is_issue() -> bool {
  true
}

Here # my comment would be added to the Table of Contents. So far I cannot think of a way to fix this without using a markdown parser to process the markdown before getting the headlines.

Links in Headlines produce wrong output

The rendered output is wrong

Code:

<!-- BEGIN mktoc -->

  - [Links in [Headlines](/headlines/)](#links-in-headlinesheadlines)
<!-- END mktoc -->

### Links in [Headlines](/headlines/)

Rendered like:

• [Links in Headlines](#links-in-headlinesheadlines)

Desired Output:

<!-- BEGIN mktoc -->

  - [Links in Headlines](#links-in-headlines)
<!-- END mktoc -->

### Links in [Headlines](/headlines/)

---

Link inside a Headline must be stripped out.

Replace structopts with clap

structopts will not receive new features and is integrated with clap, see https://github.com/texitoi/structopt#maintenance

As clap v3 is now out, and the structopt features are integrated into (almost as-is), structopt is now in maintenance mode: no new feature will be added.

almost as-is makes it seem like this shouldn't be much work.

cargo-dist

We want to use cargo-dist to replace the current release pipeline with a new shiny one. Additionally, we want to build brew taps so installation on MacOS and Linux is smoother!

https://opensource.axo.dev/cargo-dist/
https://github.com/axodotdev/cargo-dist

Extract input manipulation

The code responsible for adding the ToC is inside the make_toc function. This means a third-party user cannot get a full Markdown file generated without specifying an actual file (make_toc takes a file path).

https://github.com/KevinGimbel/mktoc/blob/main/src/lib.rs#L227-L237

Todo

Extract code into function

fn add_toc(original_file_content: String, new_toc: String) -> String

Write tests

• Adding the ToC is implicitly tested, should be explicitly tested

Add Windows binaries to release action

Binaries are now build with GitHub Actions (https://github.com/KevinGimbel/mktoc/blob/main/.github/workflows/release.yml), so Windows binaries should be supported alongside Apple and Linux ones.

I know nothing about Windows binaries so I'm unsure which of these targets make sense to build for:

• x86_64-pc-windows-msvc
• x86_64-pc-windows-gnu
• i686-pc-windows-msvc
• i686-pc-windows-gnu

Maybe all of them?