Skip to main content

mini_cite/
style.rs

1//! Presentation options for the markup [`crate::process`] emits.
2
3/// Class on the `<sup>` wrapping an inline footnote reference.
4const DEFAULT_REFERENCE_CLASS: &str = "footnote-ref";
5/// Class on the `<hr>` opening the footnote block.
6const DEFAULT_SEPARATOR_CLASS: &str = "footnotes-sep";
7/// Class on the `<ol>` holding the footnotes.
8const DEFAULT_LIST_CLASS: &str = "footnotes";
9/// Class on each footnote `<li>`.
10const DEFAULT_ITEM_CLASS: &str = "footnote";
11/// Class on the back-link closing each footnote.
12const DEFAULT_BACKLINK_CLASS: &str = "footnote-back";
13/// The back-link's text: a returning arrow.
14const DEFAULT_BACKLINK_LABEL: &str = "↩";
15
16/// Characters that would break out of the `class="…"` attribute they are written into.
17const CLASS_DELIMITERS: [char; 3] = ['"', '<', '>'];
18
19/// How the emitted citation markup is labelled and named.
20///
21/// Structure is fixed — a `<sup>` reference per citation, an `<hr>`, an `<ol>` of
22/// `<li>` footnotes, a back-link in each — and so are the `fn-N`/`fnref-N` ids the two
23/// halves are wired together with. What this configures is the part a stylesheet
24/// addresses: the class on each element, and the back-link's label.
25///
26/// Defaults follow Pandoc's names (`footnote-ref`, `footnotes`, `footnote-back`), so a
27/// stylesheet written against Pandoc's footnote output mostly applies unchanged.
28///
29/// Setting a class to `""` emits that element with no `class` attribute at all, for
30/// callers styling structurally (`li[id^="fn-"]`) rather than by class.
31///
32/// ```
33/// let style = mini_cite::CiteStyle::default()
34///     .reference_class("citation-marker")
35///     .backlink_label("↑");
36/// ```
37///
38/// # Downstream sanitizing
39///
40/// These classes only reach the page if whatever renders the Markdown preserves
41/// `class`. `ammonia`'s default policy strips it; `mini-docs` allowlists it from
42/// 0.5.0 on. Against an older or stricter sanitizer the markup still renders — the
43/// ids survive — but the classes are dropped.
44#[derive(Debug, Clone, PartialEq, Eq)]
45pub struct CiteStyle {
46    pub(crate) reference_class: String,
47    pub(crate) separator_class: String,
48    pub(crate) list_class: String,
49    pub(crate) item_class: String,
50    pub(crate) backlink_class: String,
51    pub(crate) backlink_label: String,
52}
53
54impl Default for CiteStyle {
55    fn default() -> Self {
56        Self {
57            reference_class: DEFAULT_REFERENCE_CLASS.to_string(),
58            separator_class: DEFAULT_SEPARATOR_CLASS.to_string(),
59            list_class: DEFAULT_LIST_CLASS.to_string(),
60            item_class: DEFAULT_ITEM_CLASS.to_string(),
61            backlink_class: DEFAULT_BACKLINK_CLASS.to_string(),
62            backlink_label: DEFAULT_BACKLINK_LABEL.to_string(),
63        }
64    }
65}
66
67impl CiteStyle {
68    /// Sets the class on the `<sup>` wrapping each inline reference.
69    #[must_use]
70    pub fn reference_class(mut self, class: impl Into<String>) -> Self {
71        self.reference_class = checked_class(class.into());
72        self
73    }
74
75    /// Sets the class on the `<hr>` that opens the footnote block.
76    #[must_use]
77    pub fn separator_class(mut self, class: impl Into<String>) -> Self {
78        self.separator_class = checked_class(class.into());
79        self
80    }
81
82    /// Sets the class on the `<ol>` holding the footnotes.
83    #[must_use]
84    pub fn list_class(mut self, class: impl Into<String>) -> Self {
85        self.list_class = checked_class(class.into());
86        self
87    }
88
89    /// Sets the class on each footnote `<li>`.
90    #[must_use]
91    pub fn item_class(mut self, class: impl Into<String>) -> Self {
92        self.item_class = checked_class(class.into());
93        self
94    }
95
96    /// Sets the class on the back-link closing each footnote.
97    #[must_use]
98    pub fn backlink_class(mut self, class: impl Into<String>) -> Self {
99        self.backlink_class = checked_class(class.into());
100        self
101    }
102
103    /// Sets the back-link's label — the glyph or word a reader clicks to return to
104    /// the citation.
105    ///
106    /// Written into the document verbatim, so markup here reaches the renderer as
107    /// markup and is subject to whatever sanitizing follows. An empty label leaves the
108    /// link with nothing to click; give it content, or draw one in CSS through
109    /// [`Self::backlink_class`].
110    #[must_use]
111    pub fn backlink_label(mut self, label: impl Into<String>) -> Self {
112        self.backlink_label = label.into();
113        self
114    }
115}
116
117/// Returns `class` unchanged, tripping in debug builds if it could not be written
118/// into an attribute intact.
119///
120/// A class name carrying a quote or an angle bracket does not produce a differently
121/// styled page — it produces malformed markup, silently, several layers from here.
122/// Nothing sanitizes this on the caller's behalf, so the check belongs at the boundary
123/// the value enters through (A4).
124fn checked_class(class: String) -> String {
125    debug_assert!(
126        !class.contains(CLASS_DELIMITERS),
127        "class name must not contain a quote or angle bracket: {class:?}"
128    );
129    class
130}
131
132/// Renders a `class` attribute, or nothing at all when `class` is empty.
133///
134/// The leading space belongs to the attribute rather than to the tag that holds it,
135/// so a tag with no class emits no stray whitespace either.
136pub(crate) fn class_attr(class: &str) -> String {
137    if class.is_empty() {
138        return String::new();
139    }
140
141    format!(r#" class="{class}""#)
142}
143
144#[cfg(test)]
145#[path = "../tests/unit/style.rs"]
146mod tests;