include_utils/lib.rs
1#![no_std]
2
3//! # Overview
4#![doc = crate::include_md!("README.md:description")]
5//!
6//! # Partial include modes
7//!
8//! We supports exactly the same modes of partial includes as the referred in the [mdbook].
9//!
10//! ```rust
11//! #![doc = include_utils::include_str_part!("tests/data/sample.md:2")]
12//! #![doc = include_utils::include_str_part!("tests/data/sample.md::10")]
13//! #![doc = include_utils::include_str_part!("tests/data/sample.md:2:")]
14//! #![doc = include_utils::include_str_part!("tests/data/sample.md:2:10")]
15//! ```
16//!
17//! The first line includes the second line from the file sample.md.
18//! The second one includes all lines up to the line 10, i.e. the lines
19//! from 11 till the end of file are omitted.
20//! The third command includes all file lines from the 2, i.e. the first line is omitted.
21//! this last one includes lines 2 to 10.
22//!
23//! To avoid breaking your doc when modifying included files, you can include a specific section
24//! using anchors instead of line numbers. An anchor is a pair of matching comment lines.
25//! The line beginning an anchor must match the pattern `ANCHOR: anchor_name` and
26//! similarly the ending line must match the pattern: `ANCHOR_END: anchor_name`.
27//!
28//! ```markdown
29//! <!-- ANCHOR: anchor_name -->
30//! An example of anchored section in markdown file.
31//! <!-- ANCHOR_END: anchor_name -->
32//! ```
33//!
34//! [mdbook]: https://rust-lang.github.io/mdBook/format/mdbook.html#including-portions-of-a-file
35
36/// Includes a markdown file as a string.
37///
38/// See [module][self] documentation.
39pub use include_utils_macro::include_md;
40/// Includes a part of UTF-8 encoded file as a string.
41///
42/// _**Note!** Anchors is not supported by this macro, use specific `include_md` macro to
43/// include markdown file section._
44///
45/// See [module][self] documentation.
46pub use include_utils_macro::include_str_part;