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;
90#[doc(inline)]
91pub use html::Anchorizer;
92pub use html::format_document as format_html;
93pub use html::format_document_with_plugins as format_html_with_plugins;
94pub use nodes::Node;
95pub use parser::options;
96pub use parser::{Options, ResolvedReference, parse_document};
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/// Render Markdown to HTML.
104///
105/// See the documentation of the crate root for an example.
106pub fn markdown_to_html(md: &str, options: &Options) -> String {
107    markdown_to_html_with_plugins(md, options, &options::Plugins::default())
108}
109
110/// Render Markdown to HTML using plugins.
111///
112/// See the documentation of the crate root for an example.
113pub fn markdown_to_html_with_plugins(
114    md: &str,
115    options: &Options,
116    plugins: &options::Plugins,
117) -> String {
118    let arena = Arena::new();
119    let root = parse_document(&arena, md, options);
120    let mut out = String::new();
121    format_html_with_plugins(root, options, &mut out, plugins).unwrap();
122    out
123}
124
125/// Return the version of the crate.
126pub fn version() -> &'static str {
127    env!("CARGO_PKG_VERSION")
128}
129
130/// Render Markdown back to CommonMark.
131pub fn markdown_to_commonmark(md: &str, options: &Options) -> String {
132    let arena = Arena::new();
133    let root = parse_document(&arena, md, options);
134    let mut out = String::new();
135    format_commonmark(root, options, &mut out).unwrap();
136    out
137}
138
139/// Render Markdown to CommonMark XML.
140///
141/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
142pub fn markdown_to_commonmark_xml(md: &str, options: &Options) -> String {
143    markdown_to_commonmark_xml_with_plugins(md, options, &options::Plugins::default())
144}
145
146/// Render Markdown to CommonMark XML using plugins.
147///
148/// See <https://github.com/commonmark/commonmark-spec/blob/master/CommonMark.dtd>.
149pub fn markdown_to_commonmark_xml_with_plugins(
150    md: &str,
151    options: &Options,
152    plugins: &options::Plugins,
153) -> String {
154    let arena = Arena::new();
155    let root = parse_document(&arena, md, options);
156    let mut out = String::new();
157    format_xml_with_plugins(root, options, &mut out, plugins).unwrap();
158    out
159}
comrak/lib.rs

comrak/
lib.rs
