Macro docify::compile_markdown

compile_markdown!() { /* proc-macro */ }

Allows you to use docify::embed!(..) within markdown source files via HTML comments and compiles the result for you (at compile-time).

The macro supports embed syntax within markdown files like the following:

# This is some markdown
<!-- docify::embed!("some/rust/file.rs", some_ident) -->

Which would expand to the some_ident exported item in some/rust/file.rs expanding into a Rust codeblock as a replacement for the HTML comment, i.e.:

# This is some markdown
```rust
fn hello_world() {
    println!("hello!");
}
```

There are two supported arguments, of the form:

docify::compile_markdown!("input_path", "output_path");

If input_path is a directory, then all markdown files (recursively) found within input_path will be processed (expanded) and placed in their respective locations relative to output_path.

If input_path is a file and output_path is specified, then input_path will be loaded as a markdown file, processed, and saved to output_path (which must be a file path, not a directory).

If only input_path is specified, then it is assumed to be a file, which is loaded as markdown, processed, and the result is returned as a string literal.

While files are compiling, terminal output is produced such as:

Docifying fixtures/subfolder/file_2.md => test_bin/subfolder/file_2.md

Conventions

We encourage crate authors to feature-gate their compile_markdown! calls like we do for the README.md file in this crate:

#[cfg(all(doc, feature = "generate-readme"))]
compile_markdown!("README.docify.md", "README.md");

This way the README.md will not regenerate itself every time a user of your crate runs cargo doc unless they explicitly enable the generate-readme feature for your crate.

Another convention we encourage, shown above, is naming template files foo.docify.md so they can exist alongside the generated foo.md file without collisions.