ashlar-docs

A documentation library for agents. A folder of markdown is the library: folders are categories (nested folders are subcategories), .md files are documents, served verbatim.

• Each folder may hold _category.md: frontmatter title and description, and a body that is the category's overview. It describes the folder and is not listed as a document. The root _category.md says what the library is and how to use it.
• Every document starts with YAML frontmatter: title, description (when to read it), and optionally order (an integer, lower first) and tags ([a, b]).
• [embed] runs in a build script: it walks the folder and writes a (path, include_str!) table into OUT_DIR, with rerun-if-changed on every folder and file, so adding a page needs no list to update.
• [Library::overlay_dir] adds a folder at run time (a user's own pages) on top: same path, the folder's page wins, and listings say which source each page came from.
• Symbolic links, dotfiles and non-markdown files are skipped; run-time folders are capped in depth, file count and file size.

// build.rs
fn main() {
    let dir = std::path::Path::new(&std::env::var("CARGO_MANIFEST_DIR").unwrap()).join("../../docs");
    let out = std::path::Path::new(&std::env::var("OUT_DIR").unwrap()).join("docs.rs");
    ashlar_docs::embed(&dir, &out).unwrap();
}
// lib.rs
include!(concat!(env!("OUT_DIR"), "/docs.rs")); // pub static FILES: &[(&str, &str)]
let library = ashlar_docs::Library::from_files(FILES.iter().copied());