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 nodes::Node;
95pub use parser::options;
96pub use parser::{parse_document, Options, ResolvedReference};
97pub use xml::format_document as format_xml;
98pub use xml::format_document_with_plugins as format_xml_with_plugins;
99
100/// Convenience type alias for arena used to hold nodes.
101pub type Arena<'a> = typed_arena::Arena<nodes::AstNode<'a>>;
102
103#[deprecated(
104    since = "0.45.0",
105    note = "use `comrak::options::Extension` instead of `comrak::ExtensionOptions`"
106)]
107/// Deprecated alias: use [`options::Extension`] instead of [`ExtensionOptions`].
108pub type ExtensionOptions<'c> = parser::options::Extension<'c>;
109#[deprecated(
110    since = "0.45.0",
111    note = "use `comrak::options::Parse` instead of `comrak::ParseOptions`"
112)]
113/// Deprecated alias: use [`options::Parse`] instead of [`ParseOptions`].
114pub type ParseOptions<'c> = parser::options::Parse<'c>;
115#[deprecated(
116    since = "0.45.0",
117    note = "use `comrak::options::Render` instead of `comrak::RenderOptions `"
118)]
119/// Deprecated alias: use [`options::Render`] instead of [`RenderOptions ]`.
120pub type RenderOptions = parser::options::Render;
121
122#[deprecated(
123    since = "0.45.0",
124    note = "use `comrak::options::BrokenLinkReference` instead of `comrak::BrokenLinkReference`"
125)]
126/// Deprecated alias: use [`options::BrokenLinkReference`] instead of [`BrokenLinkReference`].
127pub type BrokenLinkReference<'l> = parser::options::BrokenLinkReference<'l>;
128#[deprecated(
129    since = "0.45.0",
130    note = "use `comrak::options::ListStyleType` instead of `comrak::ListStyleType `"
131)]
132/// Deprecated alias: use [`options::ListStyleType`] instead of [`ListStyleType ]`.
133pub type ListStyleType = parser::options::ListStyleType;
134#[deprecated(
135    since = "0.45.0",
136    note = "use `comrak::options::Plugins` instead of `comrak::Plugins`"
137)]
138/// Deprecated alias: use [`options::Plugins`] instead of [`Plugins`].
139pub type Plugins<'p> = parser::options::Plugins<'p>;
140#[deprecated(
141    since = "0.45.0",
142    note = "use `comrak::options::RenderPlugins` instead of `comrak::RenderPlugins`"
143)]
144/// Deprecated alias: use [`options::RenderPlugins`] instead of [`RenderPlugins`].
145pub type RenderPlugins<'p> = parser::options::RenderPlugins<'p>;
146#[deprecated(
147    since = "0.45.0",
148    note = "use `comrak::options::WikiLinksMode` instead of `comrak::WikiLinksMode `"
149)]
150/// Deprecated alias: use [`options::WikiLinksMode`] instead of [`WikiLinksMode ]`.
151pub type WikiLinksMode = parser::options::WikiLinksMode;
152
153#[cfg(feature = "bon")]
154#[deprecated(
155    since = "0.45.0",
156    note = "use `comrak::options::ExtensionBuilder` instead of `comrak::ExtensionOptionsBuilder`"
157)]
158/// Deprecated alias: use [`options::ExtensionBuilder`] instead of [`ExtensionOptionsBuilder`].
159pub type ExtensionOptionsBuilder<'c> = parser::options::ExtensionBuilder<'c>;
160#[cfg(feature = "bon")]
161#[deprecated(
162    since = "0.45.0",
163    note = "use `comrak::options::ParseBuilder` instead of `comrak::ParseOptionsBuilder`"
164)]
165/// Deprecated alias: use [`options::ParseBuilder`] instead of [`ParseOptionsBuilder`].
166pub type ParseOptionsBuilder<'c> = parser::options::ParseBuilder<'c>;
167#[cfg(feature = "bon")]
168#[deprecated(
169    since = "0.45.0",
170    note = "use `comrak::options::RenderBuilder` instead of `comrak::RenderOptionsBuilder `"
171)]
172/// Deprecated alias: use [`options::RenderBuilder`] instead of [`RenderOptionsBuilder ]`.
173pub type RenderOptionsBuilder = parser::options::RenderBuilder;
174#[cfg(feature = "bon")]
175#[deprecated(
176    since = "0.45.0",
177    note = "use `comrak::options::PluginsBuilder` instead of `comrak::PluginsBuilder`"
178)]
179/// Deprecated alias: use [`options::PluginsBuilder`] instead of [`PluginsBuilder`].
180pub type PluginsBuilder<'p> = parser::options::PluginsBuilder<'p>;
181#[cfg(feature = "bon")]
182#[deprecated(
183    since = "0.45.0",
184    note = "use `comrak::options::RenderPluginsBuilder` instead of `comrak::RenderPluginsBuilder`"
185)]
186/// Deprecated alias: use [`options::RenderPluginsBuilder`] instead of [`RenderPluginsBuilder`].
187pub type RenderPluginsBuilder<'p> = parser::options::RenderPluginsBuilder<'p>;
188
189/// Render Markdown to HTML.
190///
191/// See the documentation of the crate root for an example.
192pub fn markdown_to_html(md: &str, options: &Options) -> String {
193    markdown_to_html_with_plugins(md, options, &options::Plugins::default())
194}
195
196/// Render Markdown to HTML using plugins.
197///
198/// See the documentation of the crate root for an example.
199pub fn markdown_to_html_with_plugins(
200    md: &str,
201    options: &Options,
202    plugins: &options::Plugins,
203) -> String {
204    let arena = Arena::new();
205    let root = parse_document(&arena, md, options);
206    let mut out = String::new();
207    format_html_with_plugins(root, options, &mut out, plugins).unwrap();
208    out
209}
210
211/// Return the version of the crate.
212pub fn version() -> &'static str {
213    env!("CARGO_PKG_VERSION")
214}
215
216/// Render Markdown back to CommonMark.
217pub fn markdown_to_commonmark(md: &str, options: &Options) -> String {
218    let arena = Arena::new();
219    let root = parse_document(&arena, md, options);
220    let mut out = String::new();
221    format_commonmark(root, options, &mut out).unwrap();
222    out
223}
224
225/// Render Markdown to CommonMark XML.
226///
227/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
228pub fn markdown_to_commonmark_xml(md: &str, options: &Options) -> String {
229    markdown_to_commonmark_xml_with_plugins(md, options, &options::Plugins::default())
230}
231
232/// Render Markdown to CommonMark XML using plugins.
233///
234/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
235pub fn markdown_to_commonmark_xml_with_plugins(
236    md: &str,
237    options: &Options,
238    plugins: &options::Plugins,
239) -> String {
240    let arena = Arena::new();
241    let root = parse_document(&arena, md, options);
242    let mut out = String::new();
243    format_xml_with_plugins(root, options, &mut out, plugins).unwrap();
244    out
245}
comrak/lib.rs

comrak/
lib.rs
