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;