https://github.com/akesson/markdown-includes
Your markdown documents with includes for externally generated texts and sections
https://github.com/akesson/markdown-includes
Last synced: about 1 month ago
JSON representation
Your markdown documents with includes for externally generated texts and sections
- Host: GitHub
- URL: https://github.com/akesson/markdown-includes
- Owner: akesson
- License: mit
- Created: 2023-03-08T09:05:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-06T07:43:44.000Z (over 3 years ago)
- Last Synced: 2026-03-04T13:16:03.152Z (4 months ago)
- Language: Rust
- Size: 48.8 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-includes
Table of contents
- [markdown-includes](#markdown-includes)
- [rustdoc](#rustdoc)
- [Example](#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](https://crates.io/crates/cargo-rdme).
The same limitations apply, especially for the syntax of [intralinks](https://github.com/orium/cargo-rdme#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:
```rust
#[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.