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};
96pub use typed_arena::Arena;
97pub use xml::format_document as format_xml;
98pub use xml::format_document_with_plugins as format_xml_with_plugins;
99
100#[cfg(feature = "bon")]
101pub use parser::{
102    ExtensionOptionsBuilder, ParseOptionsBuilder, PluginsBuilder, RenderOptionsBuilder,
103    RenderPluginsBuilder,
104};
105
106/// Legacy naming of [`ExtensionOptions`]
107pub type ComrakExtensionOptions<'c> = ExtensionOptions<'c>;
108/// Legacy naming of [`Options`]
109pub type ComrakOptions<'c> = Options<'c>;
110/// Legacy naming of [`ParseOptions`]
111pub type ComrakParseOptions<'c> = ParseOptions<'c>;
112/// Legacy naming of [`Plugins`]
113pub type ComrakPlugins<'a> = Plugins<'a>;
114/// Legacy naming of [`RenderOptions`]
115pub type ComrakRenderOptions = RenderOptions;
116/// Legacy naming of [`RenderPlugins`]
117pub type ComrakRenderPlugins<'a> = RenderPlugins<'a>;
118
119/// Render Markdown to HTML.
120///
121/// See the documentation of the crate root for an example.
122pub fn markdown_to_html(md: &str, options: &Options) -> String {
123    markdown_to_html_with_plugins(md, options, &Plugins::default())
124}
125
126/// Render Markdown to HTML using plugins.
127///
128/// See the documentation of the crate root for an example.
129pub fn markdown_to_html_with_plugins(md: &str, options: &Options, plugins: &Plugins) -> String {
130    let arena = Arena::new();
131    let root = parse_document(&arena, md, options);
132    let mut bw = BufWriter::new(Vec::new());
133    format_html_with_plugins(root, options, &mut bw, plugins).unwrap();
134    String::from_utf8(bw.into_inner().unwrap()).unwrap()
135}
136
137/// Return the version of the crate.
138pub fn version() -> &'static str {
139    env!("CARGO_PKG_VERSION")
140}
141
142/// Render Markdown back to CommonMark.
143pub fn markdown_to_commonmark(md: &str, options: &Options) -> String {
144    let arena = Arena::new();
145    let root = parse_document(&arena, md, options);
146    let mut bw = BufWriter::new(Vec::new());
147    format_commonmark(root, options, &mut bw).unwrap();
148    String::from_utf8(bw.into_inner().unwrap()).unwrap()
149}
150
151/// Render Markdown to CommonMark XML.
152/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
153pub fn markdown_to_commonmark_xml(md: &str, options: &Options) -> String {
154    markdown_to_commonmark_xml_with_plugins(md, options, &Plugins::default())
155}
156
157/// Render Markdown to CommonMark XML using plugins.
158/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
159pub fn markdown_to_commonmark_xml_with_plugins(
160    md: &str,
161    options: &Options,
162    plugins: &Plugins,
163) -> String {
164    let arena = Arena::new();
165    let root = parse_document(&arena, md, options);
166    let mut bw = BufWriter::new(Vec::new());
167    format_xml_with_plugins(root, options, &mut bw, plugins).unwrap();
168    String::from_utf8(bw.into_inner().unwrap()).unwrap()
169}
comrak/lib.rs

comrak/
lib.rs
