ndg-commonmark 2.6.0

Flavored CommonMark processor for Nix-related projects, with support for CommonMark, GFM, and Nixpkgs extensions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! # 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.
//!
//! ```rust
//! 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.
//!
//! ```rust
//! 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.
//!
//! ```rust
//! 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);
//! ```

pub mod processor;
pub mod syntax;
pub mod types;
pub mod utils;

// Re-export main API
#[cfg(feature = "gfm")]
pub use crate::processor::apply_gfm_extensions;
#[cfg(feature = "nixpkgs")]
pub use crate::processor::{
  process_block_elements,
  process_file_includes,
  process_inline_anchors,
  process_myst_autolinks,
  process_option_references,
  process_role_markup,
};
// Those don't require any feature gates, unlike above APIs.
pub use crate::{
  processor::{
    AstTransformer,
    MarkdownOptions,
    MarkdownOptionsBuilder,
    MarkdownProcessor,
    ProcessorFeature,
    ProcessorPreset,
    PromptTransformer,
    collect_markdown_files,
    create_processor,
    extract_inline_text,
    process_batch,
    process_markdown_file,
    process_markdown_file_with_basedir,
    process_markdown_string,
    process_safe,
    process_with_recovery,
  },
  syntax::{
    SyntaxConfig,
    SyntaxError,
    SyntaxHighlighter,
    SyntaxManager,
    create_default_manager,
  },
  types::{Header, IncludedFile, MarkdownResult},
};