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
5//! [github.com/kivikakk/comrak](https://github.com/kivikakk/comrak).
6//!
7//! You can use `comrak::markdown_to_html` directly:
8//!
9//! ```rust
10//! use comrak::{markdown_to_html, Options};
11//! assert_eq!(
12//!     markdown_to_html("Olá, **世界**!", &Options::default()),
13//!     "<p>Olá, <strong>世界</strong>!</p>\n"
14//! );
15//! ```
16//!
17//! Or you can parse the input into an AST yourself, manipulate it, and then use your desired
18//! formatter:
19//!
20//! ```rust
21//! use comrak::{Arena, parse_document, format_html, Options};
22//! use comrak::nodes::{NodeValue};
23//!
24//! # fn main() {
25//! let arena = Arena::new();
26//!
27//! let root = parse_document(
28//!     &arena,
29//!     "Hello, pretty world!\n\n1. Do you like [pretty](#) paintings?\n2. Or *pretty* music?\n",
30//!     &Options::default());
31//!
32//! for node in root.descendants() {
33//!     if let NodeValue::Text(ref mut text) = node.data.borrow_mut().value {
34//!         *text = text.to_mut().replace("pretty", "beautiful").into()
35//!     }
36//! }
37//!
38//! let mut html = String::new();
39//! format_html(root, &Options::default(), &mut html).unwrap();
40//!
41//! assert_eq!(
42//!     &html,
43//!     "<p>Hello, beautiful world!</p>\n\
44//!      <ol>\n\
45//!      <li>Do you like <a href=\"#\">beautiful</a> paintings?</li>\n\
46//!      <li>Or <em>beautiful</em> music?</li>\n\
47//!      </ol>\n");
48//! # }
49//! ```
50
51#![cfg_attr(docsrs, feature(doc_cfg))]
52#![deny(
53    missing_docs,
54    missing_debug_implementations,
55    missing_copy_implementations,
56    trivial_casts,
57    trivial_numeric_casts,
58    unstable_features,
59    unused_import_braces
60)]
61#![allow(
62    unknown_lints,
63    clippy::doc_markdown,
64    cyclomatic_complexity,
65    clippy::bool_to_int_with_if,
66    clippy::too_many_arguments
67)]
68
69pub mod adapters;
70pub mod arena_tree;
71pub mod html;
72pub mod nodes;
73pub mod plugins;
74
75mod character_set;
76mod cm;
77mod ctype;
78mod entity;
79mod parser;
80mod scanners;
81mod strings;
82#[cfg(test)]
83mod tests;
84mod xml;
85
86pub use cm::escape_inline as escape_commonmark_inline;
87pub use cm::escape_link_destination as escape_commonmark_link_destination;
88pub use cm::format_document as format_commonmark;
89pub use cm::format_document_with_plugins as format_commonmark_with_plugins;
90pub use html::format_document as format_html;
91pub use html::format_document_with_plugins as format_html_with_plugins;
92#[doc(inline)]
93pub use html::Anchorizer;
94pub use parser::options;
95pub use parser::{parse_document, Options, ResolvedReference};
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#[deprecated(
101    since = "0.45.0",
102    note = "use `comrak::options::Extension` instead of `comrak::ExtensionOptions`"
103)]
104/// Deprecated alias: use [`options::Extension`] instead of [`ExtensionOptions`].
105pub type ExtensionOptions<'c> = parser::options::Extension<'c>;
106#[deprecated(
107    since = "0.45.0",
108    note = "use `comrak::options::Parse` instead of `comrak::ParseOptions`"
109)]
110/// Deprecated alias: use [`options::Parse`] instead of [`ParseOptions`].
111pub type ParseOptions<'c> = parser::options::Parse<'c>;
112#[deprecated(
113    since = "0.45.0",
114    note = "use `comrak::options::Render` instead of `comrak::RenderOptions `"
115)]
116/// Deprecated alias: use [`options::Render`] instead of [`RenderOptions ]`.
117pub type RenderOptions = parser::options::Render;
118
119#[deprecated(
120    since = "0.45.0",
121    note = "use `comrak::options::BrokenLinkReference` instead of `comrak::BrokenLinkReference`"
122)]
123/// Deprecated alias: use [`options::BrokenLinkReference`] instead of [`BrokenLinkReference`].
124pub type BrokenLinkReference<'l> = parser::options::BrokenLinkReference<'l>;
125#[deprecated(
126    since = "0.45.0",
127    note = "use `comrak::options::ListStyleType` instead of `comrak::ListStyleType `"
128)]
129/// Deprecated alias: use [`options::ListStyleType`] instead of [`ListStyleType ]`.
130pub type ListStyleType = parser::options::ListStyleType;
131#[deprecated(
132    since = "0.45.0",
133    note = "use `comrak::options::Plugins` instead of `comrak::Plugins`"
134)]
135/// Deprecated alias: use [`options::Plugins`] instead of [`Plugins`].
136pub type Plugins<'p> = parser::options::Plugins<'p>;
137#[deprecated(
138    since = "0.45.0",
139    note = "use `comrak::options::RenderPlugins` instead of `comrak::RenderPlugins`"
140)]
141/// Deprecated alias: use [`options::RenderPlugins`] instead of [`RenderPlugins`].
142pub type RenderPlugins<'p> = parser::options::RenderPlugins<'p>;
143#[deprecated(
144    since = "0.45.0",
145    note = "use `comrak::options::WikiLinksMode` instead of `comrak::WikiLinksMode `"
146)]
147/// Deprecated alias: use [`options::WikiLinksMode`] instead of [`WikiLinksMode ]`.
148pub type WikiLinksMode = parser::options::WikiLinksMode;
149
150#[cfg(feature = "bon")]
151#[deprecated(
152    since = "0.45.0",
153    note = "use `comrak::options::ExtensionBuilder` instead of `comrak::ExtensionOptionsBuilder`"
154)]
155/// Deprecated alias: use [`options::ExtensionBuilder`] instead of [`ExtensionOptionsBuilder`].
156pub type ExtensionOptionsBuilder<'c> = parser::options::ExtensionBuilder<'c>;
157#[cfg(feature = "bon")]
158#[deprecated(
159    since = "0.45.0",
160    note = "use `comrak::options::ParseBuilder` instead of `comrak::ParseOptionsBuilder`"
161)]
162/// Deprecated alias: use [`options::ParseBuilder`] instead of [`ParseOptionsBuilder`].
163pub type ParseOptionsBuilder<'c> = parser::options::ParseBuilder<'c>;
164#[cfg(feature = "bon")]
165#[deprecated(
166    since = "0.45.0",
167    note = "use `comrak::options::RenderBuilder` instead of `comrak::RenderOptionsBuilder `"
168)]
169/// Deprecated alias: use [`options::RenderBuilder`] instead of [`RenderOptionsBuilder ]`.
170pub type RenderOptionsBuilder = parser::options::RenderBuilder;
171#[cfg(feature = "bon")]
172#[deprecated(
173    since = "0.45.0",
174    note = "use `comrak::options::PluginsBuilder` instead of `comrak::PluginsBuilder`"
175)]
176/// Deprecated alias: use [`options::PluginsBuilder`] instead of [`PluginsBuilder`].
177pub type PluginsBuilder<'p> = parser::options::PluginsBuilder<'p>;
178#[cfg(feature = "bon")]
179#[deprecated(
180    since = "0.45.0",
181    note = "use `comrak::options::RenderPluginsBuilder` instead of `comrak::RenderPluginsBuilder`"
182)]
183/// Deprecated alias: use [`options::RenderPluginsBuilder`] instead of [`RenderPluginsBuilder`].
184pub type RenderPluginsBuilder<'p> = parser::options::RenderPluginsBuilder<'p>;
185
186/// Render Markdown to HTML.
187///
188/// See the documentation of the crate root for an example.
189pub fn markdown_to_html(md: &str, options: &Options) -> String {
190    markdown_to_html_with_plugins(md, options, &options::Plugins::default())
191}
192
193/// Render Markdown to HTML using plugins.
194///
195/// See the documentation of the crate root for an example.
196pub fn markdown_to_html_with_plugins(
197    md: &str,
198    options: &Options,
199    plugins: &options::Plugins,
200) -> String {
201    let arena = Arena::new();
202    let root = parse_document(&arena, md, options);
203    let mut out = String::new();
204    format_html_with_plugins(root, options, &mut out, plugins).unwrap();
205    out
206}
207
208/// Return the version of the crate.
209pub fn version() -> &'static str {
210    env!("CARGO_PKG_VERSION")
211}
212
213/// Render Markdown back to CommonMark.
214pub fn markdown_to_commonmark(md: &str, options: &Options) -> String {
215    let arena = Arena::new();
216    let root = parse_document(&arena, md, options);
217    let mut out = String::new();
218    format_commonmark(root, options, &mut out).unwrap();
219    out
220}
221
222/// Render Markdown to CommonMark XML.
223///
224/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
225pub fn markdown_to_commonmark_xml(md: &str, options: &Options) -> String {
226    markdown_to_commonmark_xml_with_plugins(md, options, &options::Plugins::default())
227}
228
229/// Render Markdown to CommonMark XML using plugins.
230///
231/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
232pub fn markdown_to_commonmark_xml_with_plugins(
233    md: &str,
234    options: &Options,
235    plugins: &options::Plugins,
236) -> String {
237    let arena = Arena::new();
238    let root = parse_document(&arena, md, options);
239    let mut out = String::new();
240    format_xml_with_plugins(root, options, &mut out, plugins).unwrap();
241    out
242}
comrak/lib.rs

comrak/
lib.rs
