toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
chore: include dir names in test names
+147
-55
+2
-2
.vscode/settings.json
+2
-2
.vscode/settings.json
···
11
11
"deno.enable": true,
12
12
"editor.formatOnSave": true,
13
13
"files.associations": {
14
-
"**/*.snap": "markdown",
15
-
"**/*.snap.new": "markdown"
14
+
"**/*.md.snap": "markdown",
15
+
"**/*.md.snap.new": "markdown"
16
16
},
17
17
"javascript.validate.enable": false,
18
18
"markdown.extension.toc.levels": "2..6",
+8
-3
crates/mdbook-permalinks/src/tests.rs
+8
-3
crates/mdbook-permalinks/src/tests.rs
···
64
64
65
65
fn assert_output(doc: TestDocument, fixture: &Fixture) -> Result<()> {
66
66
let output = fixture.pages.emit(&doc.url())?;
67
-
portable_snapshots!().test(|| insta::assert_snapshot!(doc.name(), output))?;
67
+
portable_snapshots!().test(doc.name(), |name| insta::assert_snapshot!(name, output))?;
68
68
Ok(())
69
69
}
70
70
···
82
82
};
83
83
}
84
84
85
-
test_output!["tests/paths.md", "tests/urls.md", "tests/suffix.md",];
85
+
test_output![
86
+
"tests/paths.md",
87
+
"tests/urls.md",
88
+
"tests/suffix.md",
89
+
"tests/trailing-slash/index.md",
90
+
];
86
91
87
92
macro_rules! matcher {
88
93
( $pattern:pat ) => {
···
113
118
.build()
114
119
.to_report();
115
120
drop(env);
116
-
portable_snapshots!().test(|| insta::assert_snapshot!(name, report))?;
121
+
portable_snapshots!().test(name, |name| insta::assert_snapshot!(name, report))?;
117
122
Ok(())
118
123
}
crates/mdbook-permalinks/src/tests/draft.md
crates/mdbook-permalinks/src/tests/draft.md
This is a binary file and will not be displayed.
+2
crates/mdbook-permalinks/src/tests/paths.md
+2
crates/mdbook-permalinks/src/tests/paths.md
+8
-2
crates/mdbook-permalinks/src/tests/snaps/_stderr.ignored.snap
+8
-2
crates/mdbook-permalinks/src/tests/snaps/_stderr.ignored.snap
···
1
1
---
2
2
source: crates/mdbook-permalinks/src/tests.rs
3
-
assertion_line: 105
3
+
assertion_line: 121
4
4
expression: report
5
5
---
6
6
info: links ignored
7
-
╭─[crates/mdbook-permalinks/src/tests/urls.md:31:1]
7
+
╭─[crates/mdbook-permalinks/src/tests/trailing-slash/index.md:1:1]
8
+
│ <https://github.com/slorber/trailing-slash-guide>
9
+
· ─────────────────────────────────────────────────
10
+
╰────
11
+
12
+
info: links ignored
13
+
╭─[crates/mdbook-permalinks/src/tests/urls.md:33:1]
8
14
│
9
15
│ [](https://example.org/boo)
10
16
· ───────────────────────────
+15
-1
crates/mdbook-permalinks/src/tests/snaps/_stderr.permalink.snap
+15
-1
crates/mdbook-permalinks/src/tests/snaps/_stderr.permalink.snap
···
1
1
---
2
2
source: crates/mdbook-permalinks/src/tests.rs
3
-
assertion_line: 105
3
+
assertion_line: 121
4
4
expression: report
5
5
---
6
6
info: links converted to permalinks
···
35
35
· ──────────────────────┬──────────────────────┬
36
36
· │ ╰── https://example.org/git/raw/v0.0/docs/src/media/banner.webp
37
37
· ╰── https://example.org/git/tree/v0.0/docs/src/media/banner.webp
38
+
│
39
+
│ [banner-image]: /docs/src/media/banner.webp
40
+
│
41
+
│ # not found
42
+
│
43
+
│ [](../../Cargo.lock)
44
+
│
45
+
│ [](//LICENSE-MIT.md)
46
+
│
47
+
│ 
48
+
│
49
+
│ [](draft.md)
50
+
· ──────┬─────
51
+
· ╰── https://example.org/git/tree/v0.0/crates/mdbook-permalinks/src/tests/draft.md
38
52
│
39
53
╰────
40
54
+15
-5
crates/mdbook-permalinks/src/tests/snaps/_stderr.unreachable.snap
+15
-5
crates/mdbook-permalinks/src/tests/snaps/_stderr.unreachable.snap
···
1
1
---
2
2
source: crates/mdbook-permalinks/src/tests.rs
3
+
assertion_line: 121
3
4
expression: report
4
5
---
5
6
warning: links inaccessible
···
16
17
│ 
17
18
· ────────┬────────
18
19
· ╰── crates/mdbook-permalinks/src/tests/shinjuku.jpg does not exist
20
+
│
21
+
│ [](draft.md)
19
22
│
20
23
│ # gitignored
21
24
│
···
33
36
│
34
37
│ [](https://example.org/book/tests/urls/)
35
38
· ────────────────────┬───────────────────
36
-
· ╰─┤ crates/mdbook-permalinks/src/tests/urls/index.md does not exist
37
-
· │ crates/mdbook-permalinks/src/tests/urls/README.md does not exist
39
+
· ╰─┤ crates/mdbook-permalinks/src/tests/urls/index.md is not in SUMMARY.md
40
+
· │ crates/mdbook-permalinks/src/tests/urls/README.md is not in SUMMARY.md
38
41
│
39
42
│ [](https://example.org/book/tests/url)
40
43
· ───────────────────┬──────────────────
41
-
· ╰─┤ crates/mdbook-permalinks/src/tests/url.md does not exist
42
-
· │ crates/mdbook-permalinks/src/tests/url/index.md does not exist
43
-
· │ crates/mdbook-permalinks/src/tests/url/README.md does not exist
44
+
· ╰─┤ crates/mdbook-permalinks/src/tests/url.md is not in SUMMARY.md
45
+
· │ crates/mdbook-permalinks/src/tests/url/index.md is not in SUMMARY.md
46
+
· │ crates/mdbook-permalinks/src/tests/url/README.md is not in SUMMARY.md
44
47
· │ crates/mdbook-permalinks/src/tests/url does not exist
48
+
│
49
+
│ [](https://example.org/book/tests/draft)
50
+
· ────────────────────┬───────────────────
51
+
· ╰─┤ crates/mdbook-permalinks/src/tests/draft.md is not in SUMMARY.md
52
+
· │ crates/mdbook-permalinks/src/tests/draft/index.md is not in SUMMARY.md
53
+
· │ crates/mdbook-permalinks/src/tests/draft/README.md is not in SUMMARY.md
54
+
· │ crates/mdbook-permalinks/src/tests/draft does not exist
45
55
│
46
56
│ [](https://example.org/git/tree/HEAD/LICENSE-GPL.md)
47
57
· ──────────────────────────┬─────────────────────────
+3
crates/mdbook-permalinks/src/tests/snaps/paths.snap
crates/mdbook-permalinks/src/tests/snaps/paths.md.snap
+3
crates/mdbook-permalinks/src/tests/snaps/paths.snap
crates/mdbook-permalinks/src/tests/snaps/paths.md.snap
···
1
1
---
2
2
source: crates/mdbook-permalinks/src/tests.rs
3
+
assertion_line: 67
3
4
expression: output
4
5
---
5
6
# relative paths
···
37
38
[](//LICENSE-MIT.md)
38
39
39
40
41
+
42
+
[](https://example.org/git/tree/v0.0/crates/mdbook-permalinks/src/tests/draft.md)
40
43
41
44
# gitignored
42
45
crates/mdbook-permalinks/src/tests/snaps/suffix.snap
crates/mdbook-permalinks/src/tests/snaps/suffix.md.snap
crates/mdbook-permalinks/src/tests/snaps/suffix.snap
crates/mdbook-permalinks/src/tests/snaps/suffix.md.snap
+6
crates/mdbook-permalinks/src/tests/snaps/trailing-slash/index.md.snap
+6
crates/mdbook-permalinks/src/tests/snaps/trailing-slash/index.md.snap
+2
-1
crates/mdbook-permalinks/src/tests/snaps/urls.snap
crates/mdbook-permalinks/src/tests/snaps/urls.md.snap
+2
-1
crates/mdbook-permalinks/src/tests/snaps/urls.snap
crates/mdbook-permalinks/src/tests/snaps/urls.md.snap
···
1
1
---
2
2
source: crates/mdbook-permalinks/src/tests.rs
3
-
assertion_line: 61
4
3
expression: output
5
4
---
6
5
# URLs to book
···
28
27
[](https://example.org/book/tests/urls/)
29
28
30
29
[](https://example.org/book/tests/url)
30
+
31
+
[](https://example.org/book/tests/draft)
31
32
32
33
[](https://example.org/git/tree/HEAD/LICENSE-GPL.md)
33
34
+2
crates/mdbook-permalinks/src/tests/urls.md
+2
crates/mdbook-permalinks/src/tests/urls.md
+3
-5
crates/mdbook-rustdoc-links/src/main.rs
+3
-5
crates/mdbook-rustdoc-links/src/main.rs
···
134
134
FileCache::save(&env, &content).await.ok();
135
135
}
136
136
137
-
book.for_each_chapter_mut(|ch| {
138
-
if let Some(path) = &ch.source_path
139
-
&& let Some(output) = result.remove(path)
140
-
{
141
-
ch.content = output
137
+
book.for_each_text_mut(|path, content| {
138
+
if let Some(output) = result.remove(path) {
139
+
*content = output;
142
140
}
143
141
});
144
142
+4
-3
crates/mdbook-rustdoc-links/src/tests.rs
+4
-3
crates/mdbook-rustdoc-links/src/tests.rs
···
58
58
59
59
fn assert_output(doc: TestDocument, Fixture { pages, env }: &Fixture) -> Result<()> {
60
60
let output = pages.emit(&doc.url(), &env.emit_config())?;
61
-
portable_snapshots!().test(|| insta::assert_snapshot!(doc.name(), output))?;
61
+
portable_snapshots!().test(doc.name(), |name| insta::assert_snapshot!(name, output))?;
62
62
Ok(())
63
63
}
64
64
···
72
72
.logging(false)
73
73
.build()
74
74
.to_report();
75
-
portable_snapshots!()
76
-
.test(|| insta::assert_snapshot!(format!("{}.stderr", doc.name()), report))?;
75
+
portable_snapshots!().test(format!("{}.stderr", doc.name()), |name| {
76
+
insta::assert_snapshot!(name, report)
77
+
})?;
77
78
Ok(())
78
79
}
79
80
-1
crates/mdbook-rustdoc-links/src/tests/snaps/getting-started.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/getting-started.md.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/getting-started.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/getting-started.md.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/getting-started.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/getting-started.md.stderr.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/getting-started.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/getting-started.md.stderr.snap
···
1
1
---
2
2
source: crates/mdbook-rustdoc-links/src/tests.rs
3
-
assertion_line: 76
4
3
expression: report
5
4
---
6
5
info: successfully resolved all links
7
-
╭─[getting-started:55:6]
6
+
╭─[docs/src/rustdoc-links/getting-started.md:55:6]
8
7
│
9
8
│ Like [`std::thread::spawn`], [`tokio::task::spawn`] returns a
10
9
· ───────────┬────────── ───────────┬──────────
-1
crates/mdbook-rustdoc-links/src/tests/snaps/index.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/index.md.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/index.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/index.md.snap
+2
-2
crates/mdbook-rustdoc-links/src/tests/snaps/index.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/index.md.stderr.snap
+2
-2
crates/mdbook-rustdoc-links/src/tests/snaps/index.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/index.md.stderr.snap
···
1
1
---
2
-
source: crates/mdbookkit/tests/rustdoc_link.rs
2
+
source: crates/mdbook-rustdoc-links/src/tests.rs
3
3
expression: report
4
4
---
5
5
info: successfully resolved all links
6
-
╭─[index:25:5]
6
+
╭─[docs/src/rustdoc-links/index.md:25:5]
7
7
│
8
8
│ The [`option`][std::option] and [`result`][std::result] modules define optional and
9
9
· ───────────┬─────────── ───────────┬───────────
-1
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/known-issues.md.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/known-issues.md.snap
+2
-3
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/known-issues.md.stderr.snap
+2
-3
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/known-issues.md.stderr.snap
···
1
1
---
2
2
source: crates/mdbook-rustdoc-links/src/tests.rs
3
-
assertion_line: 76
4
3
expression: report
5
4
---
6
5
info: successfully resolved all links
7
-
╭─[known-issues:27:25]
6
+
╭─[docs/src/rustdoc-links/known-issues.md:27:25]
8
7
│ the derived trait by using the [macro syntax](supported-syntax.md#functions-and-macros),
9
8
│ for example, by writing [`[serde::Serialize!]`][serde::Serialize] instead of
10
9
· ────────────────────┬────────────────────
···
47
46
· ╰── https://doc.rust-lang.org/stable/core/net/ip_addr/enum.IpAddr.html#method.from
48
47
│
49
48
╰────
50
-
╭─[known-issues:121:3]
49
+
╭─[docs/src/rustdoc-links/known-issues.md:121:3]
51
50
│
52
51
│ - [~~`panic!`~~], and many other `std` macros
53
52
· ───────┬──────
-1
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.snap
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.md.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.snap
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.md.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.md.stderr.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/ra-known-quirks.md.stderr.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.snap
-1
crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.stderr.snap
+1
-2
crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.stderr.snap
crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.stderr.snap
···
1
1
---
2
2
source: crates/mdbook-rustdoc-links/src/tests.rs
3
-
assertion_line: 76
4
3
expression: report
5
4
---
6
5
info: successfully resolved all links
7
-
╭─[supported-syntax:29:10]
6
+
╭─[docs/src/rustdoc-links/supported-syntax.md:29:10]
8
7
│ >
9
8
│ > Module [`alloc`][std::alloc] — Memory allocation APIs.
10
9
· ──────────┬──────────
+16
crates/mdbookkit/src/book.rs
+16
crates/mdbookkit/src/book.rs
···
101
101
pub trait BookHelper {
102
102
fn iter_chapters(&self) -> impl Iterator<Item = (&PathBuf, &Chapter)>;
103
103
104
+
fn for_each_text_mut(&mut self, func: impl FnMut(&PathBuf, &mut String));
105
+
104
106
fn to_stdout(self, ctx: &PreprocessorContext) -> Result<()>;
105
107
}
106
108
···
115
117
};
116
118
Some((path, ch))
117
119
})
120
+
}
121
+
122
+
fn for_each_text_mut(&mut self, mut func: impl FnMut(&PathBuf, &mut String)) {
123
+
self.for_each_chapter_mut(|ch| {
124
+
let &mut Chapter {
125
+
source_path: Some(ref path),
126
+
ref mut content,
127
+
..
128
+
} = ch
129
+
else {
130
+
return;
131
+
};
132
+
func(path, content);
133
+
});
118
134
}
119
135
120
136
fn to_stdout(self, ctx: &PreprocessorContext) -> Result<()> {
+43
-13
crates/mdbookkit/src/testing.rs
+43
-13
crates/mdbookkit/src/testing.rs
···
27
27
}
28
28
29
29
impl TestDocument {
30
-
pub fn url(&self) -> Url {
30
+
pub fn cwd(&self) -> Url {
31
31
CARGO_WORKSPACE_DIR
32
32
.join(self.source_path)
33
33
.unwrap()
34
-
.join(self.target_path)
34
+
.join(".")
35
35
.unwrap()
36
36
}
37
37
38
+
pub fn url(&self) -> Url {
39
+
self.cwd().join(self.target_path).unwrap()
40
+
}
41
+
38
42
pub fn name(&self) -> String {
39
-
std::path::Path::new(self.target_path)
43
+
let dir = Path::new(self.source_path)
40
44
.with_extension("")
41
45
.file_name()
42
46
.unwrap()
43
47
.to_string_lossy()
44
-
.into_owned()
48
+
.into_owned();
49
+
50
+
let url = self.url();
51
+
let cwd = self.cwd().join(&format!("{dir}/")).unwrap();
52
+
let rel = cwd.make_relative(&url).unwrap();
53
+
54
+
if rel.starts_with("../") {
55
+
let rel = CARGO_WORKSPACE_DIR.make_relative(&url).unwrap();
56
+
if rel.starts_with("../") {
57
+
url.path_segments().unwrap().next_back().unwrap().to_owned()
58
+
} else {
59
+
rel
60
+
}
61
+
} else {
62
+
rel
63
+
}
45
64
}
46
65
}
47
66
···
49
68
macro_rules! portable_snapshots {
50
69
() => {
51
70
$crate::testing::PortableSnapshots {
52
-
file: std::path::Path::new(file!()),
71
+
source_path: std::path::Path::new(file!()),
53
72
}
54
73
};
55
74
}
···
57
76
#[derive(Debug)]
58
77
#[must_use]
59
78
pub struct PortableSnapshots {
60
-
pub file: &'static Path,
79
+
pub source_path: &'static Path,
61
80
}
62
81
63
82
impl PortableSnapshots {
64
-
pub fn test<T: FnOnce() -> R, R>(&self, cb: T) -> Result<R> {
65
-
let Self { file } = self;
83
+
pub fn test<P, F, R>(&self, name: P, cb: F) -> Result<R>
84
+
where
85
+
P: AsRef<Path>,
86
+
F: FnOnce(&str) -> R,
87
+
{
88
+
let Self { source_path } = self;
66
89
67
-
let path = file.with_extension("").join("snaps");
90
+
let name = name.as_ref();
91
+
92
+
let path = source_path.with_extension("").join("snaps");
68
93
let path = CARGO_WORKSPACE_DIR
69
-
.join(&path.to_string_lossy())
70
-
.unwrap()
71
94
.to_file_path()
72
-
.unwrap();
95
+
.unwrap()
96
+
.join(&*path.to_string_lossy())
97
+
.join(name.parent().unwrap());
98
+
99
+
let name = name
100
+
.file_name()
101
+
.unwrap_or(name.as_os_str())
102
+
.to_string_lossy();
73
103
74
104
let result = insta::Settings::clone_current()
75
105
.tap_mut(|s| s.set_snapshot_path(path))
···
82
112
(r"(?m)^(\s+)\d{3} ", "$1 "),
83
113
])
84
114
})
85
-
.bind(cb);
115
+
.bind(|| cb(&name));
86
116
87
117
Ok(result)
88
118
}
+4
docs/src/permalinks/more-ways-to-link.md
+4
docs/src/permalinks/more-ways-to-link.md
···
11
11
For such cases, the preprocessor supports some alternative link formats.
12
12
13
13
```mermaid
14
+
---
15
+
config:
16
+
theme: dark
17
+
---
14
18
stateDiagram-v2
15
19
start : Is the text included using {{#include}}
16
20
included : Is the file being included also published elsewhere <br>(e.g. crates.io)
+7
-4
docs/src/rustdoc-links/supported-syntax.md
+7
-4
docs/src/rustdoc-links/supported-syntax.md
···
15
15
> [!TIP]
16
16
>
17
17
> This page is also used for snapshot testing! To see how all the links would look like
18
-
> in Markdown after they have been processed, see
19
-
> [supported-syntax.snap](/crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.snap)
20
-
> and
21
-
> [supported-syntax.stderr.snap](/crates/mdbook-rustdoc-links/src/tests/snaps/supported-syntax.stderr.snap).
18
+
> in Markdown after they have been processed, see [supported-syntax.snap] and
19
+
> [supported-syntax.stderr.snap].
20
+
>
21
+
> [supported-syntax.snap]:
22
+
> /crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.snap
23
+
> [supported-syntax.stderr.snap]:
24
+
> /crates/mdbook-rustdoc-links/src/tests/snaps/docs/src/rustdoc-links/supported-syntax.md.stderr.snap
22
25
23
26
## Types, modules, associated items
24
27