Skip to content

Commit 987ae0c

Browse files
ehussehuss
committed
Move admonition code to a separate file
This is intended to help clean things up and isolate the admonition support in a distinct place.
1 parent 3873926 commit 987ae0c

File tree

4 files changed

+84
-77
lines changed

4 files changed

+84
-77
lines changed

‎docs/authoring.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ Admonitions use a style similar to GitHub-flavored markdown, where the style nam
182182
> This is a note.
183183
```
184184

185-
The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/lib.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/lib.rs).
185+
The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs).
186186

187187
## Style
188188

‎mdbook-spec/src/admonitions.rs

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
//! Support for admonitions using markdown blockquotes.
2+
3+
use crate::{Diagnostics, warn_or_err};
4+
use mdbook::book::Chapter;
5+
use regex::{Captures, Regex};
6+
use std::sync::LazyLock;
7+
8+
/// The Regex for the syntax for blockquotes that have a specific CSS class,
9+
/// like `> [!WARNING]`.
10+
static ADMONITION_RE: LazyLock<Regex> = LazyLock::new(|| {
11+
Regex::new(r"(?m)^ *> \[!(?<admon>[^]]+)\]\n(?<blockquote>(?: *>.*\n)+)").unwrap()
12+
});
13+
14+
/// Converts blockquotes with special headers into admonitions.
15+
///
16+
/// The blockquote should look something like:
17+
///
18+
/// ```markdown
19+
/// > [!WARNING]
20+
/// > ...
21+
/// ```
22+
///
23+
/// This will add a `<div class="alert alert-warning">` around the
24+
/// blockquote so that it can be styled differently, and injects an icon.
25+
/// The actual styling needs to be added in the `reference.css` CSS file.
26+
pub fn admonitions(chapter: &Chapter, diag: &mut Diagnostics) -> String {
27+
ADMONITION_RE
28+
.replace_all(&chapter.content, |caps: &Captures<'_>| {
29+
let lower = caps["admon"].to_lowercase();
30+
let term = to_initial_case(&caps["admon"]);
31+
let blockquote = &caps["blockquote"];
32+
let initial_spaces = blockquote.chars().position(|ch| ch != ' ').unwrap_or(0);
33+
let space = &blockquote[..initial_spaces];
34+
if lower.starts_with("edition-") {
35+
let edition = &lower[8..];
36+
return format!("{space}<div class=\"alert alert-edition\">\n\
37+
\n\
38+
{space}> <p class=\"alert-title\">\
39+
<span class=\"alert-title-edition\">{edition}</span> Edition differences</p>\n\
40+
{space} >\n\
41+
{blockquote}\n\
42+
\n\
43+
{space}</div>\n");
44+
}
45+
46+
// These icons are from GitHub, MIT License, see https://github.com/primer/octicons
47+
let svg = match lower.as_str() {
48+
"note" => "<path d=\"M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\"></path>",
49+
"warning" => "<path d=\"M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z\"></path>",
50+
_ => {
51+
warn_or_err!(
52+
diag,
53+
"admonition `{lower}` in {:?} is incorrect or not yet supported",
54+
chapter.path.as_ref().unwrap()
55+
);
56+
""
57+
}
58+
};
59+
format!(
60+
"{space}<div class=\"alert alert-{lower}\">\n\
61+
\n\
62+
{space}> <p class=\"alert-title\">\
63+
<svg viewBox=\"0 0 16 16\" width=\"18\" height=\"18\">\
64+
{svg}\
65+
</svg>{term}</p>\n\
66+
{space} >\n\
67+
{blockquote}\n\
68+
\n\
69+
{space}</div>\n",
70+
)
71+
})
72+
.to_string()
73+
}
74+
75+
fn to_initial_case(s: &str) -> String {
76+
let mut chars = s.chars();
77+
let first = chars.next().expect("not empty").to_uppercase();
78+
let rest = chars.as_str().to_lowercase();
79+
format!("{first}{rest}")
80+
}

‎mdbook-spec/src/lib.rs

Lines changed: 2 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,12 @@ use std::io;
1414
use std::ops::Range;
1515
use std::path::PathBuf;
1616

17+
mod admonitions;
1718
pub mod grammar;
1819
mod rules;
1920
mod std_links;
2021
mod test_links;
2122

22-
/// The Regex for the syntax for blockquotes that have a specific CSS class,
23-
/// like `> [!WARNING]`.
24-
static ADMONITION_RE: Lazy<Regex> = Lazy::new(|| {
25-
Regex::new(r"(?m)^ *> \[!(?<admon>[^]]+)\]\n(?<blockquote>(?: *>.*\n)+)").unwrap()
26-
});
27-
2823
/// A primitive regex to find link reference definitions.
2924
static MD_LINK_REFERENCE_DEFINITION: Lazy<Regex> =
3025
Lazy::new(|| Regex::new(r"(?m)^\[(?<label>[^]]+)]: +(?<dest>.*)").unwrap());
@@ -167,74 +162,6 @@ impl Spec {
167162
chapter.content
168163
)
169164
}
170-
171-
/// Converts blockquotes with special headers into admonitions.
172-
///
173-
/// The blockquote should look something like:
174-
///
175-
/// ```markdown
176-
/// > [!WARNING]
177-
/// > ...
178-
/// ```
179-
///
180-
/// This will add a `<div class="alert alert-warning">` around the
181-
/// blockquote so that it can be styled differently, and injects an icon.
182-
/// The actual styling needs to be added in the `reference.css` CSS file.
183-
fn admonitions(&self, chapter: &Chapter, diag: &mut Diagnostics) -> String {
184-
ADMONITION_RE
185-
.replace_all(&chapter.content, |caps: &Captures<'_>| {
186-
let lower = caps["admon"].to_lowercase();
187-
let term = to_initial_case(&caps["admon"]);
188-
let blockquote = &caps["blockquote"];
189-
let initial_spaces = blockquote.chars().position(|ch| ch != ' ').unwrap_or(0);
190-
let space = &blockquote[..initial_spaces];
191-
if lower.starts_with("edition-") {
192-
let edition = &lower[8..];
193-
return format!("{space}<div class=\"alert alert-edition\">\n\
194-
\n\
195-
{space}> <p class=\"alert-title\">\
196-
<span class=\"alert-title-edition\">{edition}</span> Edition differences</p>\n\
197-
{space} >\n\
198-
{blockquote}\n\
199-
\n\
200-
{space}</div>\n");
201-
}
202-
203-
// These icons are from GitHub, MIT License, see https://github.com/primer/octicons
204-
let svg = match lower.as_str() {
205-
"note" => "<path d=\"M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z\"></path>",
206-
"warning" => "<path d=\"M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z\"></path>",
207-
_ => {
208-
warn_or_err!(
209-
diag,
210-
"admonition `{lower}` in {:?} is incorrect or not yet supported",
211-
chapter.path.as_ref().unwrap()
212-
);
213-
""
214-
}
215-
};
216-
format!(
217-
"{space}<div class=\"alert alert-{lower}\">\n\
218-
\n\
219-
{space}> <p class=\"alert-title\">\
220-
<svg viewBox=\"0 0 16 16\" width=\"18\" height=\"18\">\
221-
{svg}\
222-
</svg>{term}</p>\n\
223-
{space} >\n\
224-
{blockquote}\n\
225-
\n\
226-
{space}</div>\n",
227-
)
228-
})
229-
.to_string()
230-
}
231-
}
232-
233-
fn to_initial_case(s: &str) -> String {
234-
let mut chars = s.chars();
235-
let first = chars.next().expect("not empty").to_uppercase();
236-
let rest = chars.as_str().to_lowercase();
237-
format!("{first}{rest}")
238165
}
239166

240167
/// Determines the git ref used for linking to a particular branch/tag in GitHub.
@@ -288,7 +215,7 @@ impl Preprocessor for Spec {
288215
if ch.is_draft_chapter() {
289216
return;
290217
}
291-
ch.content = self.admonitions(&ch, &mut diag);
218+
ch.content = admonitions::admonitions(&ch, &mut diag);
292219
ch.content = self.rule_link_references(&ch, &rules);
293220
ch.content = self.auto_link_references(&ch, &rules);
294221
ch.content = self.render_rule_definitions(&ch.content, &tests, &git_ref);

‎theme/reference.css

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Admonitions are defined with blockquotes:
1616
> [!WARNING]
1717
> This is bad!
1818
19-
See mdbook-spec/src/lib.rs.
19+
See mdbook-spec/src/admonitions.rs.
2020
*/
2121
.alert blockquote {
2222
/* Add some padding to make the vertical bar a little taller than the text.*/

0 commit comments

Comments
 (0)