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