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::{MarkdownOptionsBuilder, MarkdownProcessor};
81//!
82//! let options = MarkdownOptionsBuilder::new()
83//!   .gfm(true)
84//!   .nixpkgs(true)
85//!   .highlight_code(true)
86//!   .highlight_theme(Some("github"))
87//!   .build();
88//!
89//! let processor = MarkdownProcessor::new(options);
90//! ```
91
92pub mod processor;
93pub mod syntax;
94pub mod types;
95pub mod utils;
96
97// Re-export main API
98#[cfg(feature = "gfm")]
99pub use crate::processor::apply_gfm_extensions;
100#[cfg(feature = "ndg-flavored")]
101pub use crate::processor::process_option_references;
102#[cfg(feature = "nixpkgs")]
103pub use crate::processor::{
104  process_block_elements,
105  process_bracketed_spans,
106  process_file_includes,
107  process_inline_anchors,
108  process_myst_autolinks,
109  process_role_markup,
110};
111// Those don't require any feature gates, unlike above APIs.
112pub use crate::{
113  processor::{
114    AstTransformer,
115    MarkdownOptions,
116    MarkdownOptionsBuilder,
117    MarkdownProcessor,
118    ProcessorFeature,
119    ProcessorPreset,
120    PromptTransformer,
121    collect_markdown_files,
122    create_processor,
123    extract_inline_text,
124    process_batch,
125    process_markdown_file,
126    process_markdown_file_with_basedir,
127    process_markdown_string,
128    process_safe,
129    process_with_recovery,
130  },
131  syntax::{
132    SyntaxConfig,
133    SyntaxError,
134    SyntaxHighlighter,
135    SyntaxManager,
136    create_default_manager,
137  },
138  types::{Header, IncludedFile, MarkdownResult},
139};
ndg_commonmark/lib.rs

ndg_commonmark/
lib.rs
