cmark_hamlet/lib.rs
1//! This library provides an adapter from [pulldown-cmark][] events to
2//! [hamlet][] tokens.
3//!
4//! [pulldown-cmark]: https://github.com/google/pulldown-cmark
5//! [hamlet]: https://github.com/Nemo157/hamlet
6//!
7//! Note that block/inline html within markdown is not parsed into proper hamlet
8//! tokens.
9//!
10//! ## Example
11//!
12//! ```rust
13//! extern crate pulldown_cmark;
14//! extern crate cmark_hamlet;
15//!
16//! use std::fmt::Write;
17//! use pulldown_cmark::Parser;
18//! use cmark_hamlet::Adapter;
19//!
20//! fn main() {
21//! let md = "Ok, [google][ref]\n\n- - -\n\n\
22//! ```rust\n\
23//! use hamlet;\n\
24//! ```\n\n\
25//! [ref]: http://google.com";
26//! let ada = Adapter::new(Parser::new(md), false);
27//! let mut res = String::from("");
28//! for token in ada {
29//! write!(res, "{}", token).unwrap();
30//! }
31//! assert_eq!("<p>Ok, <a href=\"http://google.com\">google</a></p><hr />\
32//! <pre data-lang=\"rust\"><code>use hamlet;\n</code></pre>",
33//! res);
34//! }
35//! ```
36//!
37//! ## Translation
38//!
39//! ### Event mapping
40//!
41//! `pulldown_cmark` event | Action
42//! ---------------------- | ------
43//! `Start(tag)` | Context dependent; see [Tag mapping](#tag-mapping)
44//! `End(tag)` | Context dependent
45//! `Text(text)` | Context dependent; see [Text handling](#text-handling)
46//! `Html(html)` | `Token::RawText(html)`
47//! `InlineHtml(html)` | `Token::RawText(html)`
48//! `SoftBreak` | `"\n"` (see [Text handling](#text-handling))
49//! `HardBreak` | `Token` representing `<br />`
50//! `FootnoteReference(_)` | unimplemented!
51//!
52//! ### Tag mapping
53//!
54//! `pulldown_cmark` tag | Html tag name
55//! ----------------------- | -------------
56//! `BlockQuote` | `blockquote`
57//! `CodeBlock(lang)` | `pre` and `code` (see [`CodeBlock` handling](#codeblock-handling))
58//! `Code` | `code`
59//! `Emphasis` | `em`
60//! `FootnoteDefinition(_)` | unimplemented!
61//! `Header(level)` | `h{level}`
62//! `Image(_, _)` | `img`
63//! `Item` | `li`
64//! `Link(_, _)` | `a`
65//! `List(None)` | `ul`
66//! `List(Some(_))` | `ol`
67//! `Paragraph` | `p`
68//! `Rule` | `hr`
69//! `Strong` | `strong`
70//! `Table(_)` | `table`
71//! `TableCell` | `td` or `th`
72//! `TableHead` | `tr`
73//! `TableRow` | `tr`
74//!
75//! ### Text handling
76//!
77//! All successive `Text` and `SoftBreak` events are clumped together to form a
78//! single `hamlet::Text` token, if [`group_text`
79//! argument](struct.Adapter.html#method.new) provided was `true`.
80//!
81//! ### `CodeBlock` handling
82//!
83//! If `lang` attribute is not empty, then a `data-lang` attribute is added to
84//! the `pre` tag with that value.
85
86#![warn(missing_docs)]
87
88extern crate pulldown_cmark as cmark;
89#[macro_use]
90extern crate hamlet;
91
92mod adapter;
93
94pub use adapter::Adapter;