toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
chore(docs): add mermaid support
+147
-23
+1
Cargo.lock
+1
Cargo.lock
+5
docs/Cargo.toml
+5
docs/Cargo.toml
···
15
15
env_logger = { workspace = true }
16
16
gix-url = { version = "0.30.0" }
17
17
log = { workspace = true }
18
+
mdbook-markdown = { workspace = true }
18
19
mdbookkit = { workspace = true }
19
20
miette = { workspace = true }
20
21
serde = { workspace = true }
21
22
serde_json = { workspace = true }
22
23
shlex = { workspace = true }
23
24
tokio = { workspace = true }
25
+
26
+
[[bin]]
27
+
name = "mdbookkit-docs"
28
+
path = "bin/main.rs"
+21
docs/app/main.css
+21
docs/app/main.css
···
273
273
margin-block-start: 1rem;
274
274
}
275
275
}
276
+
277
+
.mermaid {
278
+
display: flex;
279
+
flex-flow: column nowrap;
280
+
justify-content: center;
281
+
min-height: 0;
282
+
283
+
&:not(:has(svg)) {
284
+
visibility: hidden;
285
+
}
286
+
}
287
+
288
+
@media screen and (width <= 420px) {
289
+
.mermaid {
290
+
padding-inline: 0.5rem;
291
+
}
292
+
293
+
figure:has(.mermaid svg) {
294
+
height: auto !important;
295
+
}
296
+
}
276
297
}
277
298
278
299
.code-header {
+21
-17
docs/app/main.ts
+21
-17
docs/app/main.ts
···
9
9
});
10
10
11
11
(async () => {
12
-
const diagrams = document.querySelectorAll("pre:has(code.language-mermaid)");
13
-
14
-
if (!diagrams.length) {
15
-
return;
12
+
if (document.querySelector("pre.mermaid")) {
13
+
const { default: mermaid } = await import("mermaid");
14
+
mermaid.initialize({
15
+
securityLevel: "antiscript",
16
+
theme: "dark",
17
+
themeVariables: {
18
+
fontFamily: `
19
+
"Noto Sans",
20
+
"Open Sans",
21
+
-apple-system,
22
+
BlinkMacSystemFont,
23
+
"Segoe UI",
24
+
"Helvetica Neue",
25
+
ui-sans-serif,
26
+
sans-serif,
27
+
"Apple Color Emoji",
28
+
"Segoe UI Emoji";
29
+
`,
30
+
},
31
+
});
32
+
await mermaid.run();
16
33
}
17
-
18
-
diagrams.forEach((elem) => {
19
-
const code = elem.querySelector("code")?.textContent;
20
-
if (!code) {
21
-
return;
22
-
}
23
-
elem.textContent = code;
24
-
elem.setAttribute("class", "mermaid");
25
-
});
26
-
27
-
const { default: mermaid } = await import("mermaid");
28
-
mermaid.initialize({});
29
-
await mermaid.run();
30
34
})();
+89
docs/bin/main.rs
+89
docs/bin/main.rs
···
1
+
use anyhow::{Context, Result};
2
+
3
+
use mdbook_markdown::pulldown_cmark::{CodeBlockKind, CowStr, Event, Parser, Tag, TagEnd};
4
+
use mdbookkit::{
5
+
book::{BookHelper, book_from_stdin},
6
+
logging::ConsoleLogger,
7
+
markdown::PatchStream,
8
+
};
9
+
10
+
fn preprocess() -> Result<()> {
11
+
let (ctx, mut book) = book_from_stdin().context("failed to read from mdbook")?;
12
+
13
+
book.for_each_text_mut(|_, content| {
14
+
let stream = Parser::new(content)
15
+
.into_offset_iter()
16
+
.scan(None, |state, (event, span)| match event {
17
+
Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(tag))) if &*tag == "mermaid" => {
18
+
*state = Some(span);
19
+
Some(None)
20
+
}
21
+
Event::Text(text) => {
22
+
if let Some(span) = state {
23
+
Some(Some((text, span.clone())))
24
+
} else {
25
+
Some(None)
26
+
}
27
+
}
28
+
Event::End(TagEnd::CodeBlock) => {
29
+
*state = None;
30
+
Some(None)
31
+
}
32
+
_ => Some(None),
33
+
})
34
+
.flat_map(|chunk| {
35
+
let (text, span) = chunk?;
36
+
let repl = vec![
37
+
Event::Start(Tag::HtmlBlock),
38
+
Event::Html(CowStr::Borrowed("<pre class=\"mermaid\">")),
39
+
Event::Html(text),
40
+
Event::Html(CowStr::Borrowed("</pre>")),
41
+
Event::End(TagEnd::HtmlBlock),
42
+
]
43
+
.into_iter();
44
+
Some((repl, span))
45
+
})
46
+
.collect::<Vec<_>>();
47
+
48
+
if !stream.is_empty() {
49
+
*content = PatchStream::new(content, stream.into_iter())
50
+
.into_string()
51
+
.unwrap();
52
+
}
53
+
});
54
+
55
+
book.to_stdout(&ctx)
56
+
}
57
+
58
+
fn main() -> Result<()> {
59
+
ConsoleLogger::install(env!("CARGO_PKG_NAME"));
60
+
let Program { command } = clap::Parser::parse();
61
+
match command {
62
+
Command::Preprocess { command: None } => preprocess(),
63
+
Command::Preprocess {
64
+
command: Some(Preprocess::Supports { .. }),
65
+
} => Ok(()),
66
+
Command::Postprocess => Ok(()),
67
+
}
68
+
}
69
+
70
+
#[derive(clap::Parser, Debug, Clone)]
71
+
struct Program {
72
+
#[command(subcommand)]
73
+
command: Command,
74
+
}
75
+
76
+
#[derive(clap::Subcommand, Debug, Clone)]
77
+
enum Command {
78
+
Preprocess {
79
+
#[command(subcommand)]
80
+
command: Option<Preprocess>,
81
+
},
82
+
Postprocess,
83
+
}
84
+
85
+
#[derive(clap::Subcommand, Debug, Clone)]
86
+
enum Preprocess {
87
+
#[clap(hide = true)]
88
+
Supports { renderer: String },
89
+
}
+4
-1
docs/book.toml
+4
-1
docs/book.toml
···
7
7
[build]
8
8
build-dir = "dist"
9
9
create-missing = false
10
-
extra-watch-dirs = ["app", "../crates"]
10
+
extra-watch-dirs = ["app", "bin", "../crates"]
11
11
12
12
[output.html]
13
13
additional-css = ["app/dist.css"]
···
53
53
54
54
[preprocessor.app]
55
55
command = "deno run --allow-all app/build/preprocessor.ts"
56
+
57
+
[preprocessor.preprocess]
58
+
command = "cargo run -- preprocess"
56
59
57
60
# [_metadata.socials."/"]
58
61
# image = "src/media/social.webp"
+6
-5
docs/src/permalinks/more-ways-to-link.md
+6
-5
docs/src/permalinks/more-ways-to-link.md
···
8
8
- Furthermore, the included document may also be intended for additional platforms,
9
9
where path-based links are not supported.
10
10
11
-
For such cases, the preprocessor supports some alternative link formats.
11
+
For such cases, the preprocessor supports some alternative link formats. Here is a
12
+
simplified guide on when to use which format:
13
+
14
+
<figure style="height: 480px">
12
15
13
16
```mermaid
14
-
---
15
-
config:
16
-
theme: dark
17
-
---
18
17
stateDiagram-v2
19
18
start : Is the text included using {{#include}}
20
19
included : Is the file being included also published elsewhere <br>(e.g. crates.io)
···
31
30
external --> bookUrl: a book page or <br>a file in the book
32
31
external --> repoUrl: a file in your repo <br>outside the book
33
32
```
33
+
34
+
</figure>
34
35
35
36
## Using absolute paths
36
37