Crate include_utils

source ·
Expand description

Overview

Often you only need a specific part of the file, e.g. relevant lines for an example, or section of README.md. This crate provides macros that can include only part of a file, similar to the mdbook specific feature.

Imagine that you want to include “usage” section from your repository readme file to the crate documentation. But you do not want to see in crate documentation some parts of readme file, like header, badges, etc. With the include_str macro you can only include the entire file content.

But with the include_md macro you can include only a specific section of the file.

Note! Unlike the built-in macro, this macros uses the CARGO_MANIFEST_DIR as the current directory instead of the directory from which macro is called.

Usage

//! # Crate overview
//! 
#![doc = include_utils::include_md!("README.md:description")]
//!
//! ## Other section

Partial include modes

We supports exactly the same modes of partial includes as the referred in the mdbook.

#![doc = include_utils::include_str_part!("tests/data/sample.md:2")]
#![doc = include_utils::include_str_part!("tests/data/sample.md::10")]
#![doc = include_utils::include_str_part!("tests/data/sample.md:2:")]
#![doc = include_utils::include_str_part!("tests/data/sample.md:2:10")]

The first line includes the second line from the file sample.md. The second one includes all lines up to the line 10, i.e. the lines from 11 till the end of file are omitted. The third command includes all file lines from the 2, i.e. the first line is omitted. this last one includes lines 2 to 10.

To avoid breaking your doc when modifying included files, you can include a specific section using anchors instead of line numbers. An anchor is a pair of matching comment lines. The line beginning an anchor must match the pattern ANCHOR: anchor_name and similarly the ending line must match the pattern: ANCHOR_END: anchor_name.

<!-- ANCHOR: anchor_name -->
An example of anchored section in markdown file.
<!-- ANCHOR_END: anchor_name -->

Macros