Skip to main content

cellix_doc/
html.rs

1//! A Markdown file as a web page that stands alone: math is inline SVG, so the page needs
2//! no scripts and no network.
3
4use pulldown_cmark::{CodeBlockKind, Event, Options, Parser, Tag, TagEnd, html};
5
6use crate::{diagram, figure, math};
7
8const STYLE: &str = "
9:root { color-scheme: light dark; --text: #1f2328; --dim: #59636e; --line: #d1d9e0;
10  --code: #f6f8fa; --link: #0969da; }
11@media (prefers-color-scheme: dark) { :root { --text: #e6edf3; --dim: #9198a1;
12  --line: #3d444d; --code: #151b23; --link: #4493f8; }
13  .math svg, .inline-math svg { filter: invert(1); }
14  .diagram { background: #fff; border-radius: 8px; } }
15body { max-width: 46rem; margin: 3rem auto; padding: 0 1.25rem; color: var(--text);
16  font: 17px/1.65 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; }
17h1, h2, h3 { line-height: 1.25; margin: 2em 0 .6em; } h1 { margin-top: 0; }
18a { color: var(--link); } img { max-width: 100%; }
19code { font: .88em ui-monospace, Menlo, monospace; background: var(--code);
20  padding: .15em .35em; border-radius: 5px; }
21pre { background: var(--code); border: 1px solid var(--line); border-radius: 8px;
22  padding: 1em; overflow: auto; } pre code { background: none; padding: 0; }
23blockquote { margin: 1em 0; padding-left: 1em; border-left: 3px solid var(--line);
24  color: var(--dim); }
25table { border-collapse: collapse; margin: 1em 0; }
26th, td { border: 1px solid var(--line); padding: .4em .8em; } th { background: var(--code); }
27.math { text-align: center; margin: 1.2em 0; overflow-x: auto; }
28.diagram { text-align: center; margin: 1.2em 0; padding: 1em; overflow-x: auto; }
29.diagram svg { max-width: 100%; height: auto; }
30mark { background: #ffec9e; color: #1f2328; padding: 0 .15em; border-radius: 3px; }
31ins { color: #1a7f37; } del { color: #cf222e; } .note { color: var(--dim); font-size: .85em; }
32blockquote[class^=markdown-alert] { color: inherit; border-left-width: 4px; }
33blockquote[class^=markdown-alert]::before { display: block; font-weight: 600; margin-top: .6em; }
34blockquote[class^=markdown-alert]:has(> .callout-title)::before { content: none; }
35.callout-title { font-weight: 600; margin-bottom: .2em; }
36.markdown-alert-note { border-color: var(--link); } .markdown-alert-note::before { content: 'Note'; }
37.markdown-alert-tip { border-color: #1a7f37; } .markdown-alert-tip::before { content: 'Tip'; }
38.markdown-alert-important { border-color: #8857e0; }
39.markdown-alert-important::before { content: 'Important'; }
40.markdown-alert-warning { border-color: #c08610; }
41.markdown-alert-warning::before { content: 'Warning'; }
42.markdown-alert-caution { border-color: #cf222e; }
43.markdown-alert-caution::before { content: 'Caution'; }
44.footnote-definition { font-size: .88em; color: var(--dim); }
45hr { border: 0; border-top: 1px solid var(--line); margin: 2em 0; }
46";
47
48/// A callout's opening line, `[!NOTE]` or Obsidian's `[!tip]- Title`: GitHub's kind it reads
49/// as, and the title written after it, if any. Obsidian's other kinds map to the nearest of
50/// GitHub's five.
51pub fn callout(line: &str) -> Option<(&'static str, Option<String>)> {
52    let rest = line.trim().strip_prefix("[!")?;
53    let (name, after) = rest.split_once(']')?;
54    let kind = match name.to_ascii_lowercase().as_str() {
55        "note" | "info" | "abstract" | "summary" | "tldr" | "todo" | "example" | "quote"
56        | "cite" => "NOTE",
57        "tip" | "hint" | "success" | "check" | "done" => "TIP",
58        "important" | "question" | "help" | "faq" => "IMPORTANT",
59        "warning" | "attention" => "WARNING",
60        "caution" | "danger" | "error" | "failure" | "fail" | "missing" | "bug" => "CAUTION",
61        _ => return None,
62    };
63    // `-` and `+` only say whether it starts folded.
64    let title = after.trim_start_matches(['-', '+']).trim();
65    Some((kind, (!title.is_empty()).then(|| title.to_string())))
66}
67
68/// Callouts as GitHub writes them, which the parser knows, keeping a title of their own in a
69/// first paragraph the page styles as the heading in place of the kind's name.
70fn callouts(markdown: &str) -> String {
71    let mut out = String::with_capacity(markdown.len());
72    for line in markdown.split_inclusive('\n') {
73        let body = line.trim_end_matches('\n');
74        let quoted = body.trim_start().strip_prefix('>');
75        match quoted.and_then(callout) {
76            Some((kind, title)) => {
77                let lead = &body[..body.len() - body.trim_start().len()];
78                out.push_str(&format!("{lead}> [!{kind}]\n"));
79                if let Some(title) = title {
80                    out.push_str(&format!(
81                        "{lead}> <p class=\"callout-title\">{}</p>\n{lead}>\n",
82                        escape(&title)
83                    ));
84                }
85            }
86            None => out.push_str(line),
87        }
88    }
89    out
90}
91
92fn escape(text: &str) -> String {
93    text.replace('&', "&amp;")
94        .replace('<', "&lt;")
95        .replace('>', "&gt;")
96}
97
98fn formula(source: &str, display: bool) -> String {
99    let shown =
100        math::svg(source, display).unwrap_or_else(|_| format!("<code>{}</code>", escape(source)));
101    if display {
102        format!("<div class=\"math\">{shown}</div>")
103    } else {
104        format!("<span class=\"inline-math\">{shown}</span>")
105    }
106}
107
108/// A block only LaTeX can draw, as what `built` has for it, or as its source.
109fn built_or_source(language: &str, source: &str, built: &Built) -> String {
110    let body = diagram::fenced_tikz(language, source);
111    match built(&body) {
112        Some(picture) => format!("<div class=\"diagram\">{picture}</div>"),
113        None => format!("<pre><code>{}</code></pre>", escape(source)),
114    }
115}
116
117/// A diagram as a picture, or its source if it can't be drawn.
118fn drawn(kind: diagram::Kind, source: &str) -> String {
119    match diagram::svg(kind, source, false) {
120        Ok(svg) => format!("<div class=\"diagram\">{svg}</div>"),
121        Err(_) => format!("<pre><code>{}</code></pre>", escape(source)),
122    }
123}
124
125/// `H~2~O` and `x^2^` as tags, leaving alone any tilde or caret that doesn't hug its text.
126fn raised(line: &str, marker: char, tag: &str) -> String {
127    let chars: Vec<char> = line.chars().collect();
128    let mut out = String::with_capacity(line.len());
129    let (mut i, mut code) = (0, false);
130    while i < chars.len() {
131        code ^= chars[i] == '`' || chars[i] == '$';
132        let close = (chars[i] == marker && !code)
133            .then(|| (i + 2..chars.len().min(i + 32)).find(|n| chars[*n] == marker))
134            .flatten()
135            .filter(|n| {
136                chars[i + 1..*n]
137                    .iter()
138                    .all(|c| !c.is_whitespace() && *c != marker)
139            });
140        match close {
141            Some(close) => {
142                let inner: String = chars[i + 1..close].iter().collect();
143                out.push_str(&format!("<{tag}>{inner}</{tag}>"));
144                i = close + 1;
145            }
146            None => {
147                out.push(chars[i]);
148                i += 1;
149            }
150        }
151    }
152    out
153}
154
155/// Highlights, tracked changes and raised text, which Markdown doesn't know, as the HTML
156/// they mean. The paper reads the same tags.
157pub fn marked(markdown: &str) -> String {
158    let pairs = [
159        ("{++", "<ins>"),
160        ("++}", "</ins>"),
161        ("{--", "<del>"),
162        ("--}", "</del>"),
163        ("{==", "<mark>"),
164        ("==}", "</mark>"),
165        ("{~~", "<del>"),
166        ("~>", "</del><ins>"),
167        ("~~}", "</ins>"),
168        ("{>>", "<span class=\"note\">"),
169        ("<<}", "</span>"),
170    ];
171    let mut out = String::with_capacity(markdown.len());
172    let mut code = false;
173    let mut highlight = false;
174    for line in markdown.split_inclusive('\n') {
175        if line.trim_start().starts_with("```") {
176            code = !code;
177        }
178        if code {
179            out.push_str(line);
180            continue;
181        }
182        // Inline code keeps its text exactly: `a == b` is code, not a highlight.
183        for (index, piece) in line.split('`').enumerate() {
184            if index > 0 {
185                out.push('`');
186            }
187            if index % 2 == 1 {
188                out.push_str(piece);
189            } else {
190                out.push_str(&marks_in(piece, &pairs, &mut highlight));
191            }
192        }
193    }
194    out
195}
196
197/// Text without CriticMarkup's `{>>…<<}` notes.
198fn without_notes(text: &str) -> String {
199    let mut out = String::with_capacity(text.len());
200    let mut rest = text;
201    while let Some(at) = rest.find("{>>") {
202        let Some(end) = rest[at..].find("<<}") else {
203            break;
204        };
205        out.push_str(rest[..at].trim_end_matches(' '));
206        rest = &rest[at + end + 3..];
207    }
208    out.push_str(rest);
209    out
210}
211
212/// Markdown's marks in text that isn't code.
213fn marks_in(text: &str, pairs: &[(&str, &str)], highlight: &mut bool) -> String {
214    // `{>>note<<}` is a reviewer's note, for the people writing, not the page.
215    let mut text = without_notes(text);
216    for (from, to) in pairs {
217        text = text.replace(from, to);
218    }
219    let text = raised(&raised(&text, '~', "sub"), '^', "sup");
220    let mut parts = text.split("==");
221    let mut out = parts.next().unwrap_or("").to_string();
222    for part in parts {
223        *highlight = !*highlight;
224        out.push_str(if *highlight { "<mark>" } else { "</mark>" });
225        out.push_str(part);
226    }
227    out
228}
229
230/// The body of a Markdown document. Formulas that won't parse stay as their source.
231pub fn body(markdown: &str) -> String {
232    body_with(markdown, &|_| None)
233}
234
235/// What's already been built for a block of LaTeX, as HTML.
236pub type Built<'a> = dyn Fn(&str) -> Option<String> + 'a;
237
238/// The body of a Markdown document, with what's been built for its blocks of TikZ.
239pub fn body_with(markdown: &str, built: &Built) -> String {
240    let options = Options::ENABLE_TABLES
241        | Options::ENABLE_TASKLISTS
242        | Options::ENABLE_STRIKETHROUGH
243        | Options::ENABLE_FOOTNOTES
244        | Options::ENABLE_GFM
245        | Options::ENABLE_MATH;
246    let markdown = &callouts(markdown);
247    let sized = figure::rewrite_sized(markdown, |image, width| {
248        format!(
249            "<img src=\"{}\" alt=\"{}\" style=\"width:{width}%\">",
250            escape(image.path),
251            escape(image.alt)
252        )
253    });
254    let (front, sized) = crate::front::split(&sized);
255    let sized = marked(sized);
256    let mut events = Vec::new();
257    if let Some(title) = &front.title {
258        events.push(Event::Html(
259            format!("<h1 class=\"title\">{}</h1>\n", escape(title)).into(),
260        ));
261    }
262    let byline: Vec<&str> = [&front.author, &front.date]
263        .into_iter()
264        .flatten()
265        .map(String::as_str)
266        .collect();
267    if !byline.is_empty() {
268        let byline = escape(&byline.join(" · "));
269        events.push(Event::Html(
270            format!("<p class=\"byline\">{byline}</p>\n").into(),
271        ));
272    }
273    let mut open: Option<(diagram::Kind, String)> = None;
274    let mut tikz: Option<(String, String)> = None;
275    for event in Parser::new_ext(&sized, options) {
276        if let Some((language, source)) = &mut tikz {
277            match event {
278                Event::Text(text) => source.push_str(&text),
279                Event::End(TagEnd::CodeBlock) => {
280                    let html = built_or_source(language, source.trim_end(), built);
281                    events.push(Event::Html(html.into()));
282                    tikz = None;
283                }
284                _ => {}
285            }
286            continue;
287        }
288        match (&mut open, event) {
289            (None, Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(language))))
290                if diagram::is_tikz(&language) =>
291            {
292                tikz = Some((language.to_string(), String::new()));
293            }
294            (None, Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(language))))
295                if diagram::kind_of(&language).is_some() =>
296            {
297                open = diagram::kind_of(&language).map(|kind| (kind, String::new()));
298            }
299            (Some((_, source)), Event::Text(text)) => source.push_str(&text),
300            (Some((kind, source)), Event::End(TagEnd::CodeBlock)) => {
301                events.push(Event::Html(drawn(*kind, source).into()));
302                open = None;
303            }
304            (_, Event::InlineMath(source)) => {
305                events.push(Event::InlineHtml(formula(&source, false).into()));
306            }
307            (_, Event::DisplayMath(source)) => {
308                events.push(Event::Html(formula(&source, true).into()));
309            }
310            (_, other) => events.push(other),
311        }
312    }
313    let mut out = String::new();
314    html::push_html(&mut out, events.into_iter());
315    out
316}
317
318/// A whole page. `base` is the folder relative links and images start from.
319pub fn page(title: &str, markdown: &str, base: &str) -> String {
320    page_with(title, markdown, base, &|_| None)
321}
322
323/// A whole page, with what's been built for its blocks of TikZ.
324pub fn page_with(title: &str, markdown: &str, base: &str, built: &Built) -> String {
325    format!(
326        "<!doctype html>\n<html><head><meta charset=\"utf-8\">\
327         <meta name=\"viewport\" content=\"width=device-width\">\
328         <title>{}</title><base href=\"file://{}/\"><style>{STYLE}</style></head>\n<body>\n{}</body></html>\n",
329        escape(title),
330        escape(base),
331        body_with(markdown, built)
332    )
333}
334
335#[cfg(test)]
336mod tests {
337    use super::*;
338
339    #[test]
340    fn a_reviewers_note_stays_out_of_an_export() {
341        let html = body("Ship it {>>check with infra<<} now.\n");
342        assert!(!html.contains("check with infra"), "{html}");
343        assert!(html.contains("Ship it now."), "{html}");
344    }
345
346    #[test]
347    fn inline_code_keeps_its_equals_signs() {
348        let html = body("Check `hits == misses` and ==this==.\n");
349        assert!(html.contains("hits == misses"), "{html}");
350        assert_eq!(html.matches("<mark>").count(), 1, "{html}");
351    }
352
353    #[test]
354    fn front_matter_is_a_title_not_a_heading_of_keys() {
355        let html = body("---\ntitle: The Plan\nauthor: Ada\n---\n\nWords.\n");
356        assert!(html.contains("<h1 class=\"title\">The Plan</h1>"), "{html}");
357        assert!(html.contains("Ada"), "{html}");
358        assert!(!html.contains("title:"), "{html}");
359    }
360
361    #[test]
362    fn a_page_carries_tables_tasks_and_math() {
363        let text = "# Title\n\n| a | b |\n|---|---|\n| 1 | 2 |\n\n- [x] done\n\nInline $x^2$ here.\n\n$$\\frac{1}{2}$$\n";
364        let html = body(text);
365        assert!(html.contains("<h1>Title</h1>"));
366        assert!(html.contains("<table>"));
367        assert!(html.contains("checkbox"));
368        assert_eq!(html.matches("<svg").count(), 2, "{html}");
369        assert!(html.contains("class=\"math\""));
370    }
371
372    #[test]
373    fn diagrams_and_sized_images_reach_the_web_page() {
374        let text = "```mermaid\nflowchart LR\n  A --> B\n```\n\n![Plot](a.png){width=40%}\n";
375        let html = body(text);
376        assert!(html.contains("class=\"diagram\""), "{html}");
377        assert!(html.contains("<svg"), "{html}");
378        assert!(!html.contains("flowchart"), "{html}");
379        assert!(html.contains("style=\"width:40%\""), "{html}");
380    }
381
382    #[test]
383    fn a_callout_keeps_its_own_title() {
384        let html = body("> [!tip]- Keep it short\n> Say less.\n\n> [!WARNING]\n> Careful.\n");
385        assert!(html.contains("markdown-alert-tip"), "{html}");
386        assert!(
387            html.contains("<p class=\"callout-title\">Keep it short</p>"),
388            "{html}"
389        );
390        assert!(html.contains("Say less."), "{html}");
391        assert!(!html.contains("[!tip]"), "{html}");
392        assert!(html.contains("markdown-alert-warning"), "{html}");
393        assert_eq!(
394            callout("[!bug] Crash"),
395            Some(("CAUTION", Some("Crash".to_string())))
396        );
397        assert_eq!(callout("[!NOTE]"), Some(("NOTE", None)));
398        assert_eq!(callout("[!nonsense]"), None);
399    }
400
401    #[test]
402    fn writing_marks_reach_the_web_page() {
403        let html = body(
404            "==key== H~2~O x^2^ {++new++}{--old--}[^a]\n\n[^a]: Note.\n\n> [!WARNING]\n> Careful.\n",
405        );
406        for want in [
407            "<mark>key</mark>",
408            "<sub>2</sub>",
409            "<sup>2</sup>",
410            "<ins>new</ins>",
411            "<del>old</del>",
412            "markdown-alert-warning",
413            "Note.",
414        ] {
415            assert!(html.contains(want), "{want}: {html}");
416        }
417    }
418
419    #[test]
420    fn tikz_reaches_the_web_page_once_it_has_been_built() {
421        let text = "```tikz\n\\draw (0,0);\n```\n";
422        assert!(
423            body(text).contains("\\draw"),
424            "unbuilt, it stays as its source"
425        );
426        let html = body_with(text, &|tex| {
427            assert!(tex.contains("\\begin{tikzpicture}"));
428            Some("<img src=\"drawn\">".to_string())
429        });
430        assert!(html.contains("<img src=\"drawn\">"), "{html}");
431        assert!(!html.contains("\\draw"), "{html}");
432    }
433
434    #[test]
435    fn a_broken_diagram_stays_as_its_source() {
436        let html = body("```mermaid\nnot a diagram (\n```\n");
437        assert!(html.contains("not a diagram"), "{html}");
438    }
439
440    #[test]
441    fn a_broken_formula_stays_as_its_source() {
442        assert!(body("A $\\frac{$ b").contains("\\frac{"));
443    }
444
445    #[test]
446    fn a_page_needs_no_network() {
447        let html = page("Doc <1>", "text", "/tmp/here");
448        assert!(html.contains("<title>Doc &lt;1&gt;</title>"));
449        assert!(html.contains("file:///tmp/here/"));
450        assert!(!html.contains("<script"));
451        assert!(!html.contains("http"));
452    }
453}