comrak/
lib.rs

1//! A 100% [CommonMark](http://commonmark.org/) and [GFM](https://github.github.com/gfm/)
2//! compatible Markdown parser.
3//!
4//! Source repository and detailed `README` is at <https://github.com/kivikakk/comrak>.
5//!
6//! You can use `comrak::markdown_to_html` directly:
7//!
8//! ```
9//! use comrak::{markdown_to_html, Options};
10//! assert_eq!(markdown_to_html("Hello, **世界**!", &Options::default()),
11//!            "<p>Hello, <strong>世界</strong>!</p>\n");
12//! ```
13//!
14//! Or you can parse the input into an AST yourself, manipulate it, and then use your desired
15//! formatter:
16//!
17//! ```
18//! use comrak::{Arena, parse_document, format_html, Options};
19//! use comrak::nodes::{AstNode, NodeValue};
20//!
21//! # fn main() {
22//! let arena = Arena::new();
23//!
24//! let root = parse_document(
25//!     &arena,
26//!     "This is my input.\n\n1. Also [my](#) input.\n2. Certainly *my* input.\n",
27//!     &Options::default());
28//!
29//! for node in root.descendants() {
30//!     if let NodeValue::Text(ref mut text) = node.data.borrow_mut().value {
31//!         *text = text.replace("my", "your");
32//!     }
33//! }
34//!
35//! let mut html = vec![];
36//! format_html(root, &Options::default(), &mut html).unwrap();
37//!
38//! assert_eq!(
39//!     String::from_utf8(html).unwrap(),
40//!     "<p>This is your input.</p>\n\
41//!      <ol>\n\
42//!      <li>Also <a href=\"#\">your</a> input.</li>\n\
43//!      <li>Certainly <em>your</em> input.</li>\n\
44//!      </ol>\n");
45//! # }
46//! ```
47
48#![cfg_attr(docsrs, feature(doc_cfg))]
49#![deny(
50    missing_docs,
51    missing_debug_implementations,
52    missing_copy_implementations,
53    trivial_casts,
54    trivial_numeric_casts,
55    unstable_features,
56    unused_import_braces
57)]
58#![allow(
59    unknown_lints,
60    clippy::doc_markdown,
61    cyclomatic_complexity,
62    clippy::bool_to_int_with_if,
63    clippy::too_many_arguments
64)]
65
66use std::io::BufWriter;
67
68pub mod adapters;
69pub mod arena_tree;
70mod character_set;
71mod cm;
72mod ctype;
73mod entity;
74pub mod html;
75pub mod nodes;
76mod parser;
77pub mod plugins;
78mod scanners;
79mod strings;
80#[cfg(test)]
81mod tests;
82mod xml;
83
84pub use cm::format_document as format_commonmark;
85pub use cm::format_document_with_plugins as format_commonmark_with_plugins;
86pub use html::format_document as format_html;
87pub use html::format_document_with_plugins as format_html_with_plugins;
88#[doc(inline)]
89pub use html::Anchorizer;
90#[allow(deprecated)]
91pub use parser::parse_document_with_broken_link_callback;
92pub use parser::{
93    parse_document, BrokenLinkCallback, BrokenLinkReference, ExtensionOptions, ListStyleType,
94    Options, ParseOptions, Plugins, RenderOptions, RenderPlugins, ResolvedReference, URLRewriter,
95    WikiLinksMode,
96};
97pub use typed_arena::Arena;
98pub use xml::format_document as format_xml;
99pub use xml::format_document_with_plugins as format_xml_with_plugins;
100
101#[cfg(feature = "bon")]
102pub use parser::{
103    ExtensionOptionsBuilder, ParseOptionsBuilder, PluginsBuilder, RenderOptionsBuilder,
104    RenderPluginsBuilder,
105};
106
107/// Legacy naming of [`ExtensionOptions`]
108pub type ComrakExtensionOptions<'c> = ExtensionOptions<'c>;
109/// Legacy naming of [`Options`]
110pub type ComrakOptions<'c> = Options<'c>;
111/// Legacy naming of [`ParseOptions`]
112pub type ComrakParseOptions<'c> = ParseOptions<'c>;
113/// Legacy naming of [`Plugins`]
114pub type ComrakPlugins<'a> = Plugins<'a>;
115/// Legacy naming of [`RenderOptions`]
116pub type ComrakRenderOptions = RenderOptions;
117/// Legacy naming of [`RenderPlugins`]
118pub type ComrakRenderPlugins<'a> = RenderPlugins<'a>;
119
120/// Render Markdown to HTML.
121///
122/// See the documentation of the crate root for an example.
123pub fn markdown_to_html(md: &str, options: &Options) -> String {
124    markdown_to_html_with_plugins(md, options, &Plugins::default())
125}
126
127/// Render Markdown to HTML using plugins.
128///
129/// See the documentation of the crate root for an example.
130pub fn markdown_to_html_with_plugins(md: &str, options: &Options, plugins: &Plugins) -> String {
131    let arena = Arena::new();
132    let root = parse_document(&arena, md, options);
133    let mut bw = BufWriter::new(Vec::new());
134    format_html_with_plugins(root, options, &mut bw, plugins).unwrap();
135    String::from_utf8(bw.into_inner().unwrap()).unwrap()
136}
137
138/// Return the version of the crate.
139pub fn version() -> &'static str {
140    env!("CARGO_PKG_VERSION")
141}
142
143/// Render Markdown back to CommonMark.
144pub fn markdown_to_commonmark(md: &str, options: &Options) -> String {
145    let arena = Arena::new();
146    let root = parse_document(&arena, md, options);
147    let mut bw = BufWriter::new(Vec::new());
148    format_commonmark(root, options, &mut bw).unwrap();
149    String::from_utf8(bw.into_inner().unwrap()).unwrap()
150}
151
152/// Render Markdown to CommonMark XML.
153/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
154pub fn markdown_to_commonmark_xml(md: &str, options: &Options) -> String {
155    markdown_to_commonmark_xml_with_plugins(md, options, &Plugins::default())
156}
157
158/// Render Markdown to CommonMark XML using plugins.
159/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
160pub fn markdown_to_commonmark_xml_with_plugins(
161    md: &str,
162    options: &Options,
163    plugins: &Plugins,
164) -> String {
165    let arena = Arena::new();
166    let root = parse_document(&arena, md, options);
167    let mut bw = BufWriter::new(Vec::new());
168    format_xml_with_plugins(root, options, &mut bw, plugins).unwrap();
169    String::from_utf8(bw.into_inner().unwrap()).unwrap()
170}
comrak/lib.rs

comrak/
lib.rs
