Expand description
§NDG-Commonmark
NDG-Commonmark is a high-performance, extensible Markdown processor for Nix, NixOS, and Nixpkgs projects. It is the AST-based Markdown parser and converter component that is capable of processing Nixpkgs-flavored Commonmark, optionally with additional flavors such as Github Flavored Markdown (GFM).
This crate is designed to be a robust, extensible and customizable cornerstone in the Nix ecosystem designed for usage in documentation tools and static site generators that would like to integrate Nix module systems as a first-class citizen while keeping convenient Markdown features under their belt for advanced use.
As NDG-Commonmark aims to replace tools such as nixos-render-docs, its syntax is a superset of the Nixpkgs-flavored Commonmark, with optional feature flags for controlling what features are available. It is fully possible to use NDG-Commonmark as a drop-in replacement for nixos-render-docs.
§Overview
- AST-based processing: Enables advanced transformations and custom syntax extensions.
- Role markup and Nix-specific features: Support for
{command}blocks, option references, file includes, and more. - Syntax highlighting: Modern, themeable code highlighting for many languages.
- Extensible: Use feature flags to enable only the extensions you need.
§Usage Examples
The following examples are designed to show how to use this crate as a library. They demonstrate how to process Markdown to HTML, extract document structure, and configure the processor for different use cases.
§Basic Markdown Processing
This example demonstrates how to convert a Markdown string to HTML using a
preset configuration. The process_markdown_string function is a
convenience wrapper for common use cases. The result contains the rendered
HTML, the document title, and extracted headers.
use ndg_commonmark::{ProcessorPreset, process_markdown_string};
let result = process_markdown_string(
"# Hello World\n\nThis is **bold** text.",
ProcessorPreset::Basic,
);
println!("HTML: {}", result.html);
println!("Title: {:?}", result.title);§Custom Processor and Options
For more control, you can create a MarkdownProcessor with custom
options. This allows you to enable or disable features such as GFM, Nixpkgs
extensions, and syntax highlighting. The processor exposes methods to render
Markdown, extract headers, and more.
use ndg_commonmark::{MarkdownOptions, MarkdownProcessor};
let processor = MarkdownProcessor::new(MarkdownOptions::default());
let result = processor.render("# Hello World\n\nThis is **bold** text.");
println!("HTML: {}", result.html);
println!("Title: {:?}", result.title);
println!("Headers: {:?}", result.headers);§Builder Pattern for Configuration
The builder pattern allows you to construct MarkdownOptions with
fine-grained control over all features. This is useful for applications that
need to dynamically configure the Markdown processor.
use ndg_commonmark::{MarkdownOptionsBuilder, MarkdownProcessor};
let options = MarkdownOptionsBuilder::new()
.gfm(true)
.nixpkgs(true)
.highlight_code(true)
.highlight_theme(Some("github"))
.build();
let processor = MarkdownProcessor::new(options);Re-exports§
pub use crate::processor::apply_gfm_extensions;pub use crate::processor::process_block_elements;pub use crate::processor::process_file_includes;pub use crate::processor::process_inline_anchors;pub use crate::processor::process_myst_autolinks;pub use crate::processor::process_option_references;pub use crate::processor::process_role_markup;pub use crate::processor::AstTransformer;pub use crate::processor::MarkdownOptions;pub use crate::processor::MarkdownOptionsBuilder;pub use crate::processor::MarkdownProcessor;pub use crate::processor::ProcessorFeature;pub use crate::processor::ProcessorPreset;pub use crate::processor::PromptTransformer;pub use crate::processor::collect_markdown_files;pub use crate::processor::create_processor;pub use crate::processor::extract_inline_text;pub use crate::processor::process_batch;pub use crate::processor::process_markdown_file;pub use crate::processor::process_markdown_file_with_basedir;pub use crate::processor::process_markdown_string;pub use crate::processor::process_safe;pub use crate::processor::process_with_recovery;pub use crate::syntax::SyntaxConfig;pub use crate::syntax::SyntaxError;pub use crate::syntax::SyntaxHighlighter;pub use crate::syntax::SyntaxManager;pub use crate::syntax::create_default_manager;pub use crate::types::Header;pub use crate::types::IncludedFile;pub use crate::types::MarkdownResult;