mdx_gen/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3// src/lib.rs
4// The README's examples use the default `syntax_highlighting` feature,
5// so it becomes the crate docs (and its doctests run) only with it.
6#![cfg_attr(feature = "syntax_highlighting", doc = include_str!("../README.md"))]
7#![cfg_attr(
8    not(feature = "syntax_highlighting"),
9    doc = "Markdown to HTML with custom blocks, enhanced tables and \
10           sanitization. The README examples need the default \
11           `syntax_highlighting` feature."
12)]
13#![doc(
14    html_favicon_url = "https://cloudcdn.pro/mdx-gen/v1/favicon.ico",
15    html_logo_url = "https://cloudcdn.pro/mdx-gen/v1/logos/mdx-gen.svg",
16    html_root_url = "https://docs.rs/mdx-gen"
17)]
18#![crate_name = "mdx_gen"]
19#![crate_type = "lib"]
20
21/// The `error` module contains error types for Markdown processing.
22pub mod error;
23
24/// The `extensions` module contains custom block and table extensions.
25pub mod extensions;
26
27/// Mermaid diagram rendering for fenced `mermaid` code blocks.
28pub mod diagrams;
29
30/// Syntax highlighting adapter for comrak's plugin system.
31#[cfg(feature = "syntax_highlighting")]
32pub mod highlight;
33
34/// Validation primitives used by [`MarkdownOptions::validate`].
35pub mod validation;
36
37/// The `markdown` module contains the core processing pipeline.
38pub mod markdown;
39
40// ── Re-exports ──────────────────────────────────────────────────────
41
42pub use error::MarkdownError;
43
44/// Applies syntax highlighting to code (standalone usage).
45///
46/// # Example
47/// ```
48/// use mdx_gen::apply_syntax_highlighting;
49/// let highlighted = apply_syntax_highlighting("fn main() {}", "rust");
50/// ```
51#[cfg(feature = "syntax_highlighting")]
52pub use highlight::apply_syntax_highlighting;
53
54/// Generates a CSS stylesheet for a built-in syntect theme so that
55/// callers can render the class-based output produced by the
56/// highlighter and the comrak adapter.
57#[cfg(feature = "syntax_highlighting")]
58pub use highlight::theme_css;
59
60pub use extensions::collect_headings;
61pub use extensions::ColumnAlignment;
62pub use extensions::CustomBlockConfig;
63pub use extensions::CustomBlockType;
64pub use extensions::Heading;
65
66/// Structured validation error surfaced by
67/// [`MarkdownOptions::validate`]. The pipeline folds failing checks
68/// into [`MarkdownError::InvalidOptionsError`]; callers can inspect
69/// the structured form directly before running the pipeline.
70pub use validation::ValidationError;
71
72/// Builder that composes multiple validation checks into a single
73/// pass — used internally by [`MarkdownOptions::validate`].
74pub use validation::Validator;
75
76/// Script block that hydrates client-side `<pre class="mermaid">`
77/// containers into inline SVG. Embed once per page — typically
78/// before `</body>`.
79pub use diagrams::hydration_script_html;
80
81/// Processes a Markdown string and converts it into HTML.
82///
83/// # Example
84/// ```
85/// use mdx_gen::{process_markdown, MarkdownOptions};
86/// use comrak::Options;
87///
88/// let markdown_input = "# Hello, World!";
89/// let mut comrak_options = Options::default();
90/// comrak_options.extension.table = true;
91///
92/// let options = MarkdownOptions::default()
93///     .with_custom_blocks(false)
94///     .with_comrak_options(comrak_options);
95///
96/// let html_output = process_markdown(markdown_input, &options).expect("Failed to process markdown");
97/// assert!(html_output.contains("<h1>Hello, World!</h1>"));
98/// ```
99///
100/// # Errors
101///
102/// Returns a `MarkdownError` if options are invalid, input exceeds
103/// the size limit, or rendering fails.
104pub use markdown::process_markdown;
105
106/// Streams processed HTML directly to a `Write` sink.
107///
108/// See [`process_markdown`] for the pipeline semantics; this variant
109/// writes the output through a caller-provided writer instead of
110/// allocating a `String`.
111pub use markdown::process_markdown_to_writer;
112
113/// Extracts plain-text content from Markdown (strips all formatting).
114///
115/// # Example
116/// ```
117/// use mdx_gen::{process_markdown_to_plain_text, MarkdownOptions};
118/// let text = process_markdown_to_plain_text("# Hello\nWorld", &MarkdownOptions::default()).unwrap();
119/// assert_eq!(text, "Hello World");
120/// ```
121pub use markdown::process_markdown_to_plain_text;
122
123/// Processes Markdown and returns both the rendered HTML and a
124/// document-order list of [`Heading`]s suitable for building a
125/// table of contents.
126pub use markdown::process_markdown_with_toc;
127
128/// Streaming variant of [`process_markdown_with_toc`].
129pub use markdown::process_markdown_with_toc_to_writer;
130
131pub use markdown::MarkdownOptions;
132pub use markdown::SanitizerConfig;
133
134/// Re-export comrak's options for convenience.
135///
136/// # Usage
137/// ```
138/// use mdx_gen::Options;
139///
140/// let mut options = Options::default();
141/// options.extension.strikethrough = true;
142/// ```
143pub use comrak::Options;
mdx_gen/lib.rs

mdx_gen/
lib.rs
