markdown-includes

Table of contents

• markdown-includes
  • rustdoc
  • Example

A simple way of including other files, rust doc and table of content in a markdown file.

For a repo's README file, you'll create a README.tpl.md which you can edit like a normal markdown file, but with the added support for fenced includes which are TOML fences with an extra name containing the configuration of the include.

rustdoc

The rustdoc part of this crate is based on modified code from cargo-rdme. The same limitations apply, especially for the syntax of intralinks

Example

src/README.tpl.md:

My title

Include a table of content:
```toml toc
header = "# Table of contents"
```

Extracted from lib.rs' rust doc:

```toml rustdoc
source = "lib.rs"
```

To generate a README.md file you add a test:

#[test]
fn update_readme() {
    markdown_includes::update("src/README.tpl.md", "README.md").unwrap();
}

This test will update the README file if necessary, but if running in a CI pipeline (the CI environment variable is set), it will fail if the README.md needs updating.