ndg_commonmark/
lib.rs

1//! # NDG-Commonmark
2//!
3//! NDG-Commonmark is a high-performance, extensible Markdown processor for Nix,
4//! `NixOS`, and Nixpkgs projects. It is the AST-based Markdown parser and
5//! converter component that is capable of processing Nixpkgs-flavored
6//! Commonmark, optionally with additional flavors such as Github Flavored
7//! Markdown (GFM).
8//!
9//! This crate is designed to be a robust, extensible and customizable
10//! cornerstone in the Nix ecosystem designed for usage in documentation tools
11//! and static site generators that would like to integrate Nix module systems
12//! as a first-class citizen while keeping convenient Markdown features under
13//! their belt for advanced use.
14//!
15//! As NDG-Commonmark aims to replace tools such as nixos-render-docs, its
16//! syntax is a superset of the Nixpkgs-flavored Commonmark, with optional
17//! feature flags for controlling what features are available. It is fully
18//! possible to use NDG-Commonmark as a drop-in replacement for
19//! nixos-render-docs.
20//!
21//! ## Overview
22//!
23//! - **AST-based processing**: Enables advanced transformations and custom
24//!   syntax extensions.
25//! - **Role markup and Nix-specific features**: Support for `{command}` blocks,
26//!   option references, file includes, and more.
27//! - **Syntax highlighting**: Modern, themeable code highlighting for many
28//!   languages.
29//! - **Extensible**: Use feature flags to enable only the extensions you need.
30//!
31//! ## Usage Examples
32//!
33//! The following examples are designed to show how to use this crate as a
34//! library. They demonstrate how to process Markdown to HTML, extract document
35//! structure, and configure the processor for different use cases.
36//!
37//! ### Basic Markdown Processing
38//!
39//! This example demonstrates how to convert a Markdown string to HTML using a
40//! preset configuration. The [`process_markdown_string`] function is a
41//! convenience wrapper for common use cases. The result contains the rendered
42//! HTML, the document title, and extracted headers.
43//!
44//! ```rust
45//! use ndg_commonmark::{ProcessorPreset, process_markdown_string};
46//!
47//! let result = process_markdown_string(
48//!   "# Hello World\n\nThis is **bold** text.",
49//!   ProcessorPreset::Basic,
50//! );
51//! println!("HTML: {}", result.html);
52//! println!("Title: {:?}", result.title);
53//! ```
54//!
55//! ### Custom Processor and Options
56//!
57//! For more control, you can create a [`MarkdownProcessor`] with custom
58//! options. This allows you to enable or disable features such as GFM, Nixpkgs
59//! extensions, and syntax highlighting. The processor exposes methods to render
60//! Markdown, extract headers, and more.
61//!
62//! ```rust
63//! use ndg_commonmark::{MarkdownOptions, MarkdownProcessor};
64//!
65//! let processor = MarkdownProcessor::new(MarkdownOptions::default());
66//! let result = processor.render("# Hello World\n\nThis is **bold** text.");
67//!
68//! println!("HTML: {}", result.html);
69//! println!("Title: {:?}", result.title);
70//! println!("Headers: {:?}", result.headers);
71//! ```
72//!
73//! ### Builder Pattern for Configuration
74//!
75//! The builder pattern allows you to construct [`MarkdownOptions`] with
76//! fine-grained control over all features. This is useful for applications that
77//! need to dynamically configure the Markdown processor.
78//!
79//! ```rust
80//! use ndg_commonmark::{
81//!   MarkdownExtension,
82//!   MarkdownOptionsBuilder,
83//!   MarkdownProcessor,
84//! };
85//!
86//! let options = MarkdownOptionsBuilder::new()
87//!   .gfm(true)
88//!   .nixpkgs(true)
89//!   .extensions(vec![
90//!     MarkdownExtension::MathDollars,
91//!     MarkdownExtension::MathCode,
92//!     MarkdownExtension::MathLatex,
93//!   ])
94//!   .highlight_code(true)
95//!   .highlight_theme(Some("github"))
96//!   .build();
97//!
98//! let processor = MarkdownProcessor::new(options);
99//! ```
100
101pub mod processor;
102pub mod syntax;
103pub mod types;
104pub mod utils;
105
106// Re-export main API
107#[cfg(feature = "gfm")]
108pub use crate::processor::apply_gfm_extensions;
109#[cfg(feature = "ndg-flavored")]
110pub use crate::processor::process_option_references;
111#[cfg(feature = "nixpkgs")]
112pub use crate::processor::{
113  process_block_elements,
114  process_bracketed_spans,
115  process_file_includes,
116  process_inline_anchors,
117  process_myst_autolinks,
118  process_role_markup,
119};
120// Those don't require any feature gates, unlike above APIs.
121pub use crate::{
122  processor::{
123    AstTransformer,
124    MarkdownExtension,
125    MarkdownOptions,
126    MarkdownOptionsBuilder,
127    MarkdownProcessor,
128    ProcessorFeature,
129    ProcessorPreset,
130    PromptTransformer,
131    collect_markdown_files,
132    create_processor,
133    extract_inline_text,
134    process_batch,
135    process_markdown_file,
136    process_markdown_file_with_basedir,
137    process_markdown_string,
138    process_safe,
139    process_with_recovery,
140    rewrite_cross_page_anchor_links,
141  },
142  syntax::{
143    SyntaxConfig,
144    SyntaxError,
145    SyntaxHighlighter,
146    SyntaxManager,
147    create_default_manager,
148  },
149  types::{
150    DuplicateAnchor,
151    DuplicateAnchorError,
152    Header,
153    IncludedFile,
154    MarkdownResult,
155    deduplicate_anchor_ids,
156    validate_anchor_ids,
157    validate_rendered_anchor_ids,
158  },
159  utils::ManpageUrlsError,
160};
ndg_commonmark/lib.rs

ndg_commonmark/
lib.rs
