Crate taboc

Source
Expand description

§Taboc

Build Icon Docs Icon Version Icon License Icon

A table of contents generator for markdown documents.

§Table of contents

§Installation

This project is available on crates.io, meaning the installation is as simple as typing:

cargo install taboc

Then you can use the taboc binary in your shell. Make sure to check out the commands with the -h flag.

§Features

§Generic options

Related flags:

  • --input - The input file (Default: ./README.md).
  • --no-file-update - Use if you want to just print the table of contents without updating the file.
  • --max-depth - The maximum heading depth to search for (Default: 6).
  • --update-existing - Use to update the existing table of contents.

§Version Control Systems

Related flags:

  • --allow-dirty - Checks if the [INPUT] file is:

    • not tracked
    • doesn’t have staged changes
    • has staged changes

  • --no-vcs - Disables VCS checks (based on the chosen VCS).

Currently supported VCS:

  • Git (default)
  • Hg
  • Pijul
  • Fossil

[!NOTE] If you try to use this script without a VCS then it’s likely that the VCS checks will fail. That’s why you should use the --no-vcs flag to explicitly not check for a VCS.

§Memmap

Use the operating system’s memory mapping for managing the file directly.

This is space efficient, however it’s often slower due to less cache locality and also less safe in the case of multiple writers causing UB.

Refer to memmap2::MmapMut#safety.

§Minimal example

If you wish to use this project as a library, all you need to have as a script is:

std::env::set_var("RUSTDOC_TEST_ARGS", "--no-file-update");

use taboc::app::App;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    App::init()?.run()?;

    Ok(())
}

Modules§

app
The user-facing logic of the program. Setting up the application is as simple as:
prelude
Re-exports. Mainly for internal usage. Could be ambiguous. Re-exports for potential external use.
utils
Crate utilities. Can be used independently if needed. The utilities consist of CLI parsing and Table of contents (TOC) generation.