mdbook-termlink 0.1.1

mdBook preprocessor that auto-links glossary terms throughout documentation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Render a single linked glossary occurrence to HTML, branching on
//! [`DisplayMode`].

use crate::config::{Config, DisplayMode};
use crate::glossary::Term;

/// Builds the HTML snippet that replaces one term occurrence in the source.
///
/// The shape depends on `config.display_mode()`:
///
/// | Mode    | Markup                                                          |
/// |---------|-----------------------------------------------------------------|
/// | Link    | `<a href title class>term</a>`                                  |
/// | Tooltip | `<abbr title tabindex class>term</abbr>`                        |
/// | Both    | `<a href class><abbr title tabindex>term</abbr></a>`            |
pub(super) fn render_term_html(
    term: &Term,
    matched_text: &str,
    glossary_path: &str,
    config: &Config,
) -> String {
    let title_attr = term
        .definition()
        .map(|d| format!(r#" title="{}""#, html_escape(d)))
        .unwrap_or_default();
    let css_class = config.css_class();
    let escaped = html_escape(matched_text);
    let anchor = term.anchor();

    match config.display_mode() {
        DisplayMode::Link => format!(
            r#"<a href="{glossary_path}#{anchor}"{title_attr} class="{css_class}">{escaped}</a>"#,
        ),
        DisplayMode::Tooltip => {
            format!(r#"<abbr{title_attr} tabindex="0" class="{css_class}">{escaped}</abbr>"#)
        }
        DisplayMode::Both => format!(
            r#"<a href="{glossary_path}#{anchor}" class="{css_class}"><abbr{title_attr} tabindex="0">{escaped}</abbr></a>"#,
        ),
    }
}

/// Escapes the four HTML metacharacters we ever emit into attribute values
/// and text nodes: `&`, `<`, `>`, `"`. Single quotes never appear in our
/// output because we always quote attributes with `"`.
fn html_escape(text: &str) -> String {
    text.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_support::config_with_display_mode;

    fn term_with_definition() -> Term {
        Term::with_definition("API", Some("Application Programming Interface".to_string()))
    }

    #[test]
    fn html_escape_escapes_metacharacters() {
        assert_eq!(html_escape("a < b"), "a &lt; b");
        assert_eq!(html_escape("a & b"), "a &amp; b");
        assert_eq!(html_escape("<script>"), "&lt;script&gt;");
        assert_eq!(html_escape(r#"say "hello""#), "say &quot;hello&quot;");
    }

    #[test]
    fn snapshot_link_mode() {
        let html = render_term_html(
            &term_with_definition(),
            "API",
            "glossary.html",
            &config_with_display_mode(DisplayMode::Link),
        );
        insta::assert_snapshot!(html);
    }

    #[test]
    fn snapshot_tooltip_mode() {
        let html = render_term_html(
            &term_with_definition(),
            "API",
            "glossary.html",
            &config_with_display_mode(DisplayMode::Tooltip),
        );
        insta::assert_snapshot!(html);
    }

    #[test]
    fn snapshot_both_mode() {
        let html = render_term_html(
            &term_with_definition(),
            "API",
            "glossary.html",
            &config_with_display_mode(DisplayMode::Both),
        );
        insta::assert_snapshot!(html);
    }

    #[test]
    fn snapshot_link_mode_without_definition() {
        let html = render_term_html(
            &Term::new("API"),
            "API",
            "glossary.html",
            &config_with_display_mode(DisplayMode::Link),
        );
        insta::assert_snapshot!(html);
    }
}