toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
[link-forever] check canonical URLs
+597
-139
+1
-1
.cargo/config.toml
+1
-1
.cargo/config.toml
+3
-2
.github/workflows/ci.yml
+3
-2
.github/workflows/ci.yml
···
7
7
8
8
pull_request:
9
9
10
+
schedule:
11
+
- cron: "27 0 * * *"
12
+
10
13
env:
11
14
CARGO_TERM_COLOR: always
12
15
···
19
22
matrix:
20
23
toolchain:
21
24
- "stable"
22
-
- "1.81.0"
23
25
24
26
steps:
25
27
- uses: actions/checkout@v4
···
76
78
ra-version:
77
79
- "2025-03-17"
78
80
- "2025-03-04"
79
-
- "2025-02-17" # 1.85.0
80
81
- "nightly"
81
82
82
83
steps:
+4
-2
Cargo.toml
+4
-2
Cargo.toml
···
1
1
[workspace.package]
2
+
publish = false
3
+
2
4
authors = ["Tony Wu <tonywu6@protonmail.com>"]
3
-
edition = "2021"
4
5
license = "MIT OR Apache-2.0"
5
-
publish = false
6
6
repository = "https://github.com/tonywu6/mdbookkit"
7
+
8
+
edition = "2021"
7
9
rust-version = "1.81.0"
8
10
9
11
[profile.dev.package]
+1
README.md
+1
README.md
···
1
+
# mdbookkit
+11
-3
crates/mdbookkit/Cargo.toml
+11
-3
crates/mdbookkit/Cargo.toml
···
1
1
[package]
2
2
name = "mdbookkit"
3
+
publish = true
3
4
version = "0.1.0"
4
5
5
6
authors.workspace = true
6
-
edition.workspace = true
7
+
description = "Toolkit for mdBook."
7
8
license.workspace = true
8
-
publish.workspace = true
9
+
readme = "README.md"
9
10
repository.workspace = true
11
+
12
+
edition.workspace = true
10
13
rust-version.workspace = true
11
14
12
15
autobins = false
···
48
51
tokio-util = { version = "0.7.13", features = ["compat"], optional = true }
49
52
toml = { workspace = true, optional = true }
50
53
tower = { version = "0.5.2", optional = true }
51
-
url = { workspace = true, optional = true }
54
+
url = { workspace = true, features = ["serde"], optional = true }
52
55
53
56
[dev-dependencies]
54
57
insta = { workspace = true }
···
104
107
common-cli = ["dep:clap", "dep:mdbook", "dep:toml"]
105
108
106
109
default = []
110
+
111
+
# aliases
112
+
113
+
mdbook-link-forever = ["link-forever"]
114
+
mdbook-rustdoc-link = ["rustdoc-link"]
107
115
108
116
[[bin]]
109
117
name = "mdbook-rustdoc-link"
+47
crates/mdbookkit/README.md
+47
crates/mdbookkit/README.md
···
1
+
# mdbookkit — _toolkit for 📖 [mdBook]!_
2
+
3
+
[`mdbookkit`] provides quality-of-life plugins that you can use in your mdBook project.
4
+
5
+
Right now, there are two mdBook [preprocessors], both for generating **correct and
6
+
versioned** external links from **easy-to-write** markup.
7
+
8
+
- [**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link)
9
+
10
+
_rustdoc_-style linking for Rust APIs: write types and function names, get links to
11
+
docs.rs
12
+
13
+
- [**`mdbook-link-forever`**](https://tonywu6.github.io/mdbookkit/link-forever)
14
+
15
+
_Permalinks_ for your source tree: write relative paths, get links to GitHub.
16
+
17
+
> [!TIP]
18
+
>
19
+
> Preprocessors are standalone programs that mdBook invokes to transform your Markdown
20
+
> sources before rendering them.
21
+
22
+
## Installation
23
+
24
+
If you are interested in any of these plugins, visit their respective pages for usage
25
+
instructions, linked above.
26
+
27
+
If you want to install all of them:
28
+
29
+
```bash
30
+
cargo install mdbookkit --all-features
31
+
```
32
+
33
+
Precompiled binaries are also available from [GitHub releases][gh-releases].
34
+
35
+
## License
36
+
37
+
This project is released under the [Apache 2.0 License](/LICENSE-APACHE.md) and the
38
+
[MIT License](/LICENSE-MIT.md).
39
+
40
+
<!-- prettier-ignore-start -->
41
+
42
+
[mdBook]: https://rust-lang.github.io/mdBook/
43
+
[`mdbookkit`]: https://crates.io/crates/mdbookkit
44
+
[preprocessors]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
45
+
[gh-releases]: https://github.com/tonywu6/mdbookkit/releases
46
+
47
+
<!-- prettier-ignore-end -->
+1
-1
crates/mdbookkit/src/bin/link_forever/diagnostic.rs
+1
-1
crates/mdbookkit/src/bin/link_forever/diagnostic.rs
···
22
22
for (base, link) in content
23
23
.pages
24
24
.iter()
25
-
.flat_map(|(base, page)| page.rel_links.iter().map(|link| (base.as_ref(), link)))
25
+
.flat_map(|(base, page)| page.rel_links.iter().map(move |link| (base, link)))
26
26
{
27
27
let diagnostic = LinkDiagnostic { link, base, root };
28
28
sorted
+6
-4
crates/mdbookkit/src/bin/link_forever/git.rs
+6
-4
crates/mdbookkit/src/bin/link_forever/git.rs
···
51
51
};
52
52
53
53
let fmt_link: Box<dyn PermalinkFormat> = {
54
-
if let Some(pat) = &config.url_pattern {
54
+
if let Some(pat) = &config.repo_url_template {
55
55
CustomPermalink {
56
-
pattern: pat.clone(),
56
+
pattern: pat
57
+
.parse()
58
+
.context("failed to parse `repo-url-template` as a valid url")?,
57
59
reference,
58
60
}
59
61
.pipe(Box::new)
60
62
} else if let Ok(github) = find_github_repo(&repo, &book.config)
61
-
.and_then(|(owner, repo)| Ok(GitHubPermalink::new(&owner, &repo, &reference)?))
63
+
.map(|(owner, repo)| GitHubPermalink::new(&owner, &repo, &reference))
62
64
.context("failed to determine GitHub url for permalinks")
63
65
.tap_err(log_warning!(detailed))
64
66
.tap_err(|_| {
65
67
log::warn!("help: set `output.html.git-repository-url` to a GitHub url");
66
-
log::warn!("or set `preprocessor.link-forever.url-format` to a custom format")
68
+
log::warn!("or use `preprocessor.link-forever.repo-url-template`")
67
69
})
68
70
{
69
71
Box::new(github)
+280
-90
crates/mdbookkit/src/bin/link_forever/mod.rs
+280
-90
crates/mdbookkit/src/bin/link_forever/mod.rs
···
4
4
fmt::Debug,
5
5
hash::Hash,
6
6
ops::Range,
7
+
str::FromStr,
7
8
sync::Arc,
8
9
};
9
10
···
49
50
.iter_mut()
50
51
.flat_map(|(base, page)| page.rel_links.iter_mut().map(move |link| (base, link)))
51
52
{
52
-
let Ok(mut url) = if link.link.starts_with('/') {
53
+
let url = if link.link.starts_with('/') {
53
54
self.vcs_root.join(&link.link[1..])
54
55
} else {
55
56
base.join(&link.link)
56
57
}
57
58
.context("couldn't derive url")
58
-
.tap_err(log_debug!()) else {
59
+
.tap_err(log_debug!());
60
+
61
+
let Ok(url) = url else {
59
62
link.status = LinkStatus::Ignored;
60
63
continue;
61
64
};
62
65
63
-
if url.scheme() != "file" {
64
-
link.status = LinkStatus::Ignored;
65
-
continue;
66
-
};
66
+
let env = self;
67
+
let fragments = &fragments;
68
+
69
+
Resolver {
70
+
link,
71
+
url,
72
+
env,
73
+
fragments,
74
+
}
75
+
.resolve();
76
+
}
77
+
78
+
fragments.tap_mut(|f| f.restore(content));
79
+
}
80
+
81
+
#[inline]
82
+
fn validate_self(&self) {
83
+
debug_assert!(
84
+
self.book_src.as_str().ends_with('/'),
85
+
"book_src should have a trailing slash, got {}",
86
+
self.book_src
87
+
);
88
+
debug_assert!(
89
+
self.vcs_root.as_str().ends_with('/'),
90
+
"vcs_root should have a trailing slash, got {}",
91
+
self.vcs_root
92
+
);
93
+
}
94
+
}
67
95
68
-
let Ok(path) = url.to_file_path() else {
69
-
link.status = LinkStatus::Ignored;
70
-
continue;
71
-
};
96
+
#[must_use]
97
+
struct Resolver<'a, 'r> {
98
+
url: Url,
99
+
link: &'a mut RelativeLink<'r>,
100
+
env: &'a Environment,
101
+
fragments: &'a Fragments,
102
+
}
72
103
73
-
if !matches!(
74
-
path.try_exists()
75
-
.context("could not access path")
76
-
.tap_err(log_debug!()),
77
-
Ok(true)
78
-
) {
79
-
link.status = LinkStatus::NoSuchPath;
80
-
continue;
104
+
impl Resolver<'_, '_> {
105
+
fn resolve(self) {
106
+
if self.url.scheme() == "file" {
107
+
self.resolve_file()
108
+
} else if let Some(book) = &self.env.config.book_url {
109
+
if let Some(page) = book.0.make_relative(&self.url) {
110
+
self.resolve_page(page);
111
+
} else {
112
+
self.link.status = LinkStatus::Ignored;
81
113
}
114
+
} else {
115
+
self.link.status = LinkStatus::Ignored
116
+
}
117
+
}
82
118
83
-
let Ok(rel) = self
84
-
.book_src
85
-
.make_relative(&url)
86
-
.context("url is from a different origin")
87
-
.tap_err(log_debug!())
88
-
else {
89
-
continue;
90
-
};
119
+
fn resolve_file(self) {
120
+
let Self {
121
+
link,
122
+
url,
123
+
env,
124
+
fragments,
125
+
} = self;
126
+
127
+
let Ok(path) = url.to_file_path() else {
128
+
link.status = LinkStatus::Ignored;
129
+
return;
130
+
};
91
131
92
-
let always_link = self
93
-
.config
94
-
.always_link
95
-
.iter()
96
-
.any(|suffix| url.path().ends_with(suffix));
132
+
let exists = path
133
+
.try_exists()
134
+
.context("could not access path")
135
+
.tap_err(log_debug!());
97
136
98
-
if !rel.starts_with("../") && !always_link {
99
-
link.status = LinkStatus::Published;
137
+
if !matches!(exists, Ok(true)) {
138
+
link.status = LinkStatus::NoSuchPath;
139
+
return;
140
+
}
100
141
101
-
let Some(fragment) = url
102
-
.fragment()
103
-
.and_then(|f| percent_decode_str(f).decode_utf8().ok().or(Some(f.into())))
104
-
.map(|f| f.into_owned())
105
-
else {
106
-
continue;
107
-
};
142
+
let Ok(rel) = env
143
+
.book_src
144
+
.make_relative(&url)
145
+
.context("url is from a different origin")
146
+
.tap_err(log_debug!())
147
+
else {
148
+
return;
149
+
};
108
150
109
-
url.set_fragment(None);
151
+
let always_link = env
152
+
.config
153
+
.always_link
154
+
.iter()
155
+
.any(|suffix| url.path().ends_with(suffix));
110
156
111
-
let found = fragments
112
-
.0
113
-
.get(&url)
114
-
.map(|f| f.contains(&fragment))
115
-
.unwrap_or(false);
157
+
if !rel.starts_with("../") && !always_link {
158
+
link.status = LinkStatus::Published;
159
+
Self {
160
+
link,
161
+
url,
162
+
env,
163
+
fragments,
164
+
}
165
+
.resolve_fragment();
166
+
return;
167
+
}
116
168
117
-
url.set_fragment(Some(&fragment));
169
+
let Ok(rel) = env
170
+
.vcs_root
171
+
.make_relative(&url)
172
+
.context("url is from a different origin")
173
+
.tap_err(log_debug!())
174
+
else {
175
+
return;
176
+
};
118
177
119
-
if !found {
120
-
link.status = LinkStatus::NoSuchFragment;
121
-
}
178
+
if rel.starts_with("../") {
179
+
link.status = LinkStatus::External;
180
+
return;
181
+
}
122
182
123
-
continue;
183
+
match env.fmt_link.link_to(&rel) {
184
+
Ok(href) => {
185
+
link.status = LinkStatus::Permalink;
186
+
link.link = href.as_str().to_owned().into();
124
187
}
188
+
Err(err) => link.status = LinkStatus::Error(format!("{err}")),
189
+
}
190
+
}
125
191
126
-
let Ok(rel) = self
127
-
.vcs_root
128
-
.make_relative(&url)
129
-
.context("url is from a different origin")
130
-
.tap_err(log_debug!())
131
-
else {
192
+
fn resolve_page(self, page: String) {
193
+
let Self {
194
+
url,
195
+
link,
196
+
env,
197
+
fragments,
198
+
} = self;
199
+
200
+
let path = {
201
+
let mut path = page;
202
+
if let Some(idx) = path.find('#') {
203
+
path.truncate(idx)
204
+
};
205
+
if let Some(idx) = path.find('?') {
206
+
path.truncate(idx)
207
+
};
208
+
path.strip_suffix(".html")
209
+
.map(ToOwned::to_owned)
210
+
.unwrap_or(path)
211
+
};
212
+
213
+
if path.starts_with("../") {
214
+
link.status = LinkStatus::Ignored;
215
+
return;
216
+
}
217
+
218
+
let mut not_found = vec![];
219
+
220
+
for file in [
221
+
format!("{path}.md"),
222
+
format!("{path}/index.md"),
223
+
format!("{path}/README.md"),
224
+
] {
225
+
let Ok(file) = self.env.book_src.join(&file).tap_err(log_debug!()) else {
132
226
continue;
133
227
};
134
228
135
-
if rel.starts_with("../") {
136
-
link.status = LinkStatus::External;
229
+
let Ok(path) = file.to_file_path() else {
137
230
continue;
138
-
}
231
+
};
232
+
233
+
let exists = path
234
+
.try_exists()
235
+
.context("could not access path")
236
+
.tap_err(log_debug!());
237
+
238
+
if matches!(exists, Ok(true)) {
239
+
let url = {
240
+
let mut file = file;
241
+
file.set_query(url.query());
242
+
file.set_fragment(url.fragment());
243
+
file
244
+
};
139
245
140
-
match self.fmt_link.link_to(&rel) {
141
-
Ok(href) => {
142
-
link.status = LinkStatus::Permalink;
143
-
link.link = href.as_str().to_owned().into();
246
+
link.link = url.to_string().into();
247
+
link.status = LinkStatus::Published;
248
+
249
+
Self {
250
+
link,
251
+
url,
252
+
env,
253
+
fragments,
144
254
}
145
-
Err(err) => link.status = LinkStatus::Error(format!("{err}")),
255
+
.resolve_fragment();
256
+
257
+
return;
146
258
}
259
+
260
+
not_found.push(file);
147
261
}
148
262
149
-
fragments.tap_mut(|f| f.restore(content));
263
+
link.link = not_found[0].to_string().into();
264
+
link.status = LinkStatus::NoSuchPath;
150
265
}
151
266
152
-
#[inline]
153
-
fn validate_self(&self) {
154
-
debug_assert!(
155
-
self.book_src.as_str().ends_with('/'),
156
-
"book_src should have a trailing slash, got {}",
157
-
self.book_src
158
-
);
267
+
fn resolve_fragment(self) {
268
+
let Self {
269
+
link,
270
+
mut url,
271
+
fragments,
272
+
..
273
+
} = self;
274
+
275
+
let Some(fragment) = url
276
+
.fragment()
277
+
.and_then(|f| percent_decode_str(f).decode_utf8().ok().or(Some(f.into())))
278
+
.map(|f| f.into_owned())
279
+
else {
280
+
return;
281
+
};
282
+
283
+
url.set_fragment(None);
284
+
285
+
let found = fragments
286
+
.0
287
+
.get(&url)
288
+
.map(|f| f.contains(&fragment))
289
+
.unwrap_or(false);
290
+
291
+
url.set_fragment(Some(&fragment));
159
292
160
-
debug_assert!(
161
-
self.vcs_root.as_str().ends_with('/'),
162
-
"vcs_root should have a trailing slash, got {}",
163
-
self.vcs_root
164
-
);
293
+
if !found {
294
+
link.status = LinkStatus::NoSuchFragment;
295
+
}
165
296
}
166
297
}
167
298
···
423
554
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
424
555
#[cfg_attr(feature = "common-cli", derive(clap::Parser))]
425
556
pub struct Config {
426
-
/// Use a custom URL pattern for constructing permalinks to platforms other than
427
-
/// GitHub.
557
+
/// Use a custom link format for platforms other than GitHub.
428
558
///
429
559
/// Should be a string that contains the following placeholders that will be
430
560
/// filled in at build time:
···
435
565
/// For example, the following configures generated links to use GitLab's format:
436
566
///
437
567
/// ```toml
438
-
/// url-pattern = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"
568
+
/// repo-url-template = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"
439
569
/// ```
440
570
///
441
571
/// Note that information such as repo owner or name will not be filled in. If URLs to
···
443
573
#[serde(default)]
444
574
#[cfg_attr(
445
575
feature = "common-cli",
446
-
arg(long, value_name("PATTERN"), verbatim_doc_comment)
576
+
arg(long, value_name("FORMAT"), verbatim_doc_comment)
447
577
)]
448
-
pub url_pattern: Option<String>,
578
+
pub repo_url_template: Option<String>,
449
579
450
-
/// Convert some paths to permalinks even if they are under the `src/` directory.
580
+
/// Specify the canonical URL at which you deploy your book.
581
+
///
582
+
/// Should be a qualified URL. For example:
583
+
///
584
+
/// ```toml
585
+
/// book-url = "https://me.github.io/my-awesome-crate/"
586
+
/// ```
587
+
///
588
+
/// Enables validation of hard-coded links to book pages. The preprocessor will
589
+
/// warn you about links that are no longer valid (file not found) at build time.
590
+
///
591
+
/// This is mainly used with mdBook's `{{#include}}` feature, where sometimes you
592
+
/// have to specify full URLs because path-based links are not supported.
593
+
#[serde(default)]
594
+
#[cfg_attr(
595
+
feature = "common-cli",
596
+
arg(long, value_name("URL"), verbatim_doc_comment)
597
+
)]
598
+
pub book_url: Option<UrlPrefix>,
599
+
600
+
/// Convert some paths to permalinks even if they are under `src/`.
451
601
///
452
602
/// By default, links to files in your book's `src/` directory will not be transformed,
453
603
/// since they are already copied to build output as static files. If you want such files
···
500
650
}
501
651
502
652
pub struct GitHubPermalink {
503
-
prefix: Url,
653
+
owner: String,
654
+
repo: String,
655
+
reference: String,
504
656
}
505
657
506
658
impl PermalinkFormat for GitHubPermalink {
507
659
fn link_to(&self, relpath: &str) -> Result<Url> {
508
-
Ok(self.prefix.join(relpath)?)
660
+
let owner = &self.owner;
661
+
let repo = &self.repo;
662
+
let reference = &self.reference;
663
+
Ok(format!("https://github.com/{owner}/{repo}/tree/{reference}/{relpath}").parse()?)
509
664
}
510
665
}
511
666
512
667
impl GitHubPermalink {
513
-
pub fn new(owner: &str, repo: &str, reference: &str) -> Result<Self, url::ParseError> {
514
-
let prefix = format!("https://github.com/{owner}/{repo}/tree/{reference}/").parse()?;
515
-
Ok(Self { prefix })
668
+
pub fn new(owner: &str, repo: &str, reference: &str) -> Self {
669
+
Self {
670
+
owner: owner.into(),
671
+
repo: repo.into(),
672
+
reference: reference.into(),
673
+
}
516
674
}
517
675
}
518
676
519
677
pub struct CustomPermalink {
520
-
pub pattern: String,
678
+
pub pattern: Url,
521
679
pub reference: String,
522
680
}
523
681
···
525
683
fn link_to(&self, relpath: &str) -> Result<Url> {
526
684
Ok(self
527
685
.pattern
686
+
.as_str()
528
687
.replace("{ref}", &self.reference)
529
688
.replace("{path}", relpath)
530
689
.parse()?)
690
+
}
691
+
}
692
+
693
+
#[derive(Debug, Clone)]
694
+
pub struct UrlPrefix(Url);
695
+
696
+
impl From<Url> for UrlPrefix {
697
+
fn from(mut url: Url) -> Self {
698
+
if !url.path().ends_with('/') {
699
+
let path = format!("{}/", url.path());
700
+
url.set_path(&path);
701
+
}
702
+
Self(url)
703
+
}
704
+
}
705
+
706
+
impl FromStr for UrlPrefix {
707
+
type Err = url::ParseError;
708
+
709
+
fn from_str(s: &str) -> Result<Self, Self::Err> {
710
+
Ok(Self::from(s.parse::<Url>()?))
711
+
}
712
+
}
713
+
714
+
impl<'de> Deserialize<'de> for UrlPrefix {
715
+
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
716
+
where
717
+
D: serde::Deserializer<'de>,
718
+
{
719
+
let url = Url::deserialize(deserializer)?;
720
+
Ok(Self::from(url))
531
721
}
532
722
}
533
723
+10
-6
crates/mdbookkit/tests/link_forever.rs
+10
-6
crates/mdbookkit/tests/link_forever.rs
···
3
3
use tap::Pipe;
4
4
5
5
use mdbookkit::{
6
-
bin::link_forever::{Environment, GitHubPermalink, Pages},
6
+
bin::link_forever::{Config, Environment, GitHubPermalink, Pages},
7
7
markdown::mdbook_markdown,
8
8
};
9
+
use url::Url;
9
10
use util_testing::{portable_snapshots, test_document, CARGO_WORKSPACE_DIR};
10
11
11
12
#[test]
···
13
14
let env = Environment {
14
15
book_src: CARGO_WORKSPACE_DIR.join("crates/mdbookkit/tests/")?,
15
16
vcs_root: CARGO_WORKSPACE_DIR.clone(),
16
-
fmt_link: GitHubPermalink::new("lorem", "ipsum", "dolor")?.pipe(Box::new),
17
+
fmt_link: GitHubPermalink::new("lorem", "ipsum", "dolor").pipe(Box::new),
17
18
markdown: mdbook_markdown(),
18
-
config: Default::default(),
19
+
config: Config {
20
+
book_url: Some("https://example.org/book".parse::<Url>()?.into()),
21
+
..Default::default()
22
+
},
19
23
};
20
24
21
25
let mut pages = Pages::new(mdbook_markdown());
···
27
31
pages.insert(side_page.file.clone(), side_page.source)?;
28
32
29
33
env.resolve(&mut pages);
30
-
31
-
let output = pages.emit(&main_page.file)?;
32
34
33
35
let name = main_page.name.clone();
34
36
35
-
portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}"), output))?;
37
+
let output = pages.emit(&main_page.file)?;
36
38
37
39
let report = env
38
40
.report(&pages)
···
44
46
.to_report();
45
47
46
48
portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}.stderr"), report))?;
49
+
50
+
portable_snapshots!().test(|| insta::assert_snapshot!(format!("{name}"), output))?;
47
51
48
52
Ok(())
49
53
}
+10
crates/mdbookkit/tests/snaps/link_forever/link-forever.snap
+10
crates/mdbookkit/tests/snaps/link_forever/link-forever.snap
···
49
49
## heading: $\sqrt{3x-1}+(1+x)^2$
50
50
51
51
## heading: <https://räksmörgås.josefsson.org/>
52
+
53
+
# canonical urls
54
+
55
+
found: <https://example.org/book/tests/ra-known-quirks>
56
+
57
+
found: <https://example.org/book/tests/ra-known-quirks.html>
58
+
59
+
missing: <https://example.org/book/404>
60
+
61
+
ignored: <https://example.com/book/ra-known-quirks>
+38
crates/mdbookkit/tests/snaps/link_forever/link-forever.stderr.snap
+38
crates/mdbookkit/tests/snaps/link_forever/link-forever.stderr.snap
···
13
13
46 │
14
14
47 │ ## heading: <https://räksmörgås.josefsson.org/>
15
15
· ───────────────────────────────────
16
+
48 │
17
+
49 │ # canonical urls
18
+
50 │
19
+
51 │ found: <https://example.org/book/tests/ra-known-quirks>
20
+
52 │
21
+
53 │ found: <https://example.org/book/tests/ra-known-quirks.html>
22
+
54 │
23
+
55 │ missing: <https://example.org/book/404>
24
+
56 │
25
+
57 │ ignored: <https://example.com/book/ra-known-quirks>
26
+
· ──────────────────────────────────────────
16
27
╰────
17
28
18
29
info: file under src/
···
44
55
· ─────────────────────────────────────────────────
45
56
32 │
46
57
╰────
58
+
╭─[crates/mdbookkit/tests/tests/link-forever.md:51:8]
59
+
50 │
60
+
51 │ found: <https://example.org/book/tests/ra-known-quirks>
61
+
· ────────────────────────────────────────────────
62
+
52 │
63
+
53 │ found: <https://example.org/book/tests/ra-known-quirks.html>
64
+
· ─────────────────────────────────────────────────────
65
+
54 │
66
+
╰────
47
67
48
68
info: path converted to permalink
49
69
╭─[crates/mdbookkit/tests/tests/link-forever.md:3:1]
···
83
103
· ──────────────┬──────────────
84
104
· ╰── file does not exist at path: crates/mdbookkit/tests/tests/shinjuku.jpg
85
105
40 │
106
+
41 │ # fragment not found
107
+
42 │
108
+
43 │ [associated items](../tests/ra-known-quirks.md#associated_items_on_primitive_types)
109
+
44 │
110
+
45 │ ## heading: $\sqrt{3x-1}+(1+x)^2$
111
+
46 │
112
+
47 │ ## heading: <https://räksmörgås.josefsson.org/>
113
+
48 │
114
+
49 │ # canonical urls
115
+
50 │
116
+
51 │ found: <https://example.org/book/tests/ra-known-quirks>
117
+
52 │
118
+
53 │ found: <https://example.org/book/tests/ra-known-quirks.html>
119
+
54 │
120
+
55 │ missing: <https://example.org/book/404>
121
+
· ───────────────┬──────────────
122
+
· ╰── file does not exist at path: crates/mdbookkit/tests/404.md
123
+
56 │
86
124
╰────
87
125
88
126
warning: no such fragment
+4
crates/mdbookkit/tests/snaps/rustdoc_link/getting-started.snap
+4
crates/mdbookkit/tests/snaps/rustdoc_link/getting-started.snap
···
1
1
---
2
2
source: crates/mdbookkit/tests/rustdoc_link.rs
3
+
assertion_line: 31
3
4
expression: output
4
5
---
5
6
# Getting started
···
22
23
```
23
24
cargo install mdbookkit --features rustdoc-link
24
25
```
26
+
27
+
Or you can grab precompiled binaries from [GitHub releases][gh-releases].
25
28
26
29
## Configure
27
30
···
92
95
[ra-install]: https://rust-analyzer.github.io/book/rust_analyzer_binary.html
93
96
[open-docs]: https://rust-analyzer.github.io/book/features.html#open-docs
94
97
[ra-extension]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer
98
+
[gh-releases]: https://github.com/tonywu6/mdbookkit/releases
95
99
96
100
<!-- prettier-ignore-end -->
+7
-6
crates/mdbookkit/tests/snaps/rustdoc_link/getting-started.stderr.snap
+7
-6
crates/mdbookkit/tests/snaps/rustdoc_link/getting-started.stderr.snap
···
1
1
---
2
-
source: crates/rustdoc-link/tests/lib.rs
2
+
source: crates/mdbookkit/tests/rustdoc_link.rs
3
+
assertion_line: 44
3
4
expression: report
4
5
---
5
6
info: successfully resolved all links
6
-
╭─[getting-started:50:6]
7
-
49 │
8
-
50 │ Like [`std::thread::spawn`], [`tokio::task::spawn`] returns a
7
+
╭─[getting-started:52:6]
8
+
51 │
9
+
52 │ Like [`std::thread::spawn`], [`tokio::task::spawn`] returns a
9
10
· ───────────┬────────── ───────────┬──────────
10
11
· │ ╰── https://docs.rs/tokio/1.44.1/tokio/task/spawn/fn.spawn.html
11
12
· ╰── https://doc.rust-lang.org/stable/std/thread/fn.spawn.html
12
-
51 │ [`JoinHandle`][tokio::task::JoinHandle] struct.
13
+
53 │ [`JoinHandle`][tokio::task::JoinHandle] struct.
13
14
· ───────────────────┬───────────────────
14
15
· ╰── https://docs.rs/tokio/1.44.1/tokio/runtime/task/join/struct.JoinHandle.html
15
-
52 │
16
+
54 │
16
17
╰────
+3
-1
crates/mdbookkit/tests/snaps/rustdoc_link/rustdoc-link.snap
+3
-1
crates/mdbookkit/tests/snaps/rustdoc_link/rustdoc-link.snap
···
1
1
---
2
2
source: crates/mdbookkit/tests/rustdoc_link.rs
3
+
assertion_line: 31
3
4
expression: output
4
5
---
5
6
# mdbook-rustdoc-link
···
44
45
45
46
For **writing documentation** —
46
47
47
-
- To know more about how the preprocessor is resolving items into links, see
48
+
- To know more about how the preprocessor is resolving items into links, including
49
+
[feature-gated items](rustdoc-link/name-resolution.md#feature-gated-items), see
48
50
[Name resolution](rustdoc-link/name-resolution.md).
49
51
- To know how to link to other types of items like
50
52
[functions, macros](rustdoc-link/supported-syntax.md#functions-and-macros), and
+10
crates/mdbookkit/tests/tests/link-forever.md
+10
crates/mdbookkit/tests/tests/link-forever.md
···
45
45
## heading: $\sqrt{3x-1}+(1+x)^2$
46
46
47
47
## heading: <https://räksmörgås.josefsson.org/>
48
+
49
+
# canonical urls
50
+
51
+
found: <https://example.org/book/tests/ra-known-quirks>
52
+
53
+
found: <https://example.org/book/tests/ra-known-quirks.html>
54
+
55
+
missing: <https://example.org/book/404>
56
+
57
+
ignored: <https://example.com/book/ra-known-quirks>
+3
docs/README.md
+3
docs/README.md
+9
-7
docs/book.toml
+9
-7
docs/book.toml
···
8
8
[build]
9
9
build-dir = "dist"
10
10
create-missing = false
11
-
extra-watch-dirs = ["app"]
11
+
extra-watch-dirs = ["app", "../crates/mdbookkit"]
12
12
13
13
[rust]
14
14
edition = "2021"
···
27
27
28
28
[preprocessor.rustdoc-link-options]
29
29
before = ["rustdoc-link"]
30
-
command = "cargo run --package util-clap-reflect -- --reflect rustdoc-link-options"
30
+
command = "cargo run --quiet --package util-clap-reflect -- --reflect rustdoc-link-options"
31
31
32
32
[preprocessor.link-forever-options]
33
33
before = ["rustdoc-link"]
34
-
command = "cargo run --package util-clap-reflect -- --reflect link-forever-options"
34
+
command = "cargo run --quiet --package util-clap-reflect -- --reflect link-forever-options"
35
35
36
36
[preprocessor.rustdoc-link]
37
37
after = ["links"]
38
38
cache-dir = "build"
39
39
cargo-features = ["clap/unstable-doc"]
40
-
command = "cargo run --package mdbookkit --bin mdbook-rustdoc-link --features=rustdoc-link --release"
40
+
command = "cargo run --quiet --package mdbookkit --bin mdbook-rustdoc-link --all-features --release"
41
41
manifest-dir = "."
42
-
rust-analyzer = "cargo run --package util-rust-analyzer -- analyzer"
42
+
rust-analyzer = "cargo run --quiet --package util-rust-analyzer --all-features -- analyzer"
43
43
44
44
[preprocessor.link-forever]
45
45
after = ["rustdoc-link"]
46
46
always-link = [".rs"]
47
-
command = "cargo run --package mdbookkit --bin mdbook-link-forever --features=link-forever --release"
47
+
book-url = "https://tonywu6.github.io/mdbookkit/"
48
+
command = "cargo run --quiet --package mdbookkit --bin mdbook-link-forever --all-features --release"
48
49
49
50
[preprocessor.rust-analyzer-version]
50
51
after = ["rustdoc-link"]
51
-
command = "cargo run --package util-rust-analyzer --features=ra-version -- version"
52
+
command = "cargo run --quiet --package util-rust-analyzer --all-features -- version"
52
53
53
54
[preprocessor.alerts]
54
55
after = ["rustdoc-link"]
56
+
command = "cargo bin mdbook-alerts"
55
57
56
58
[preprocessor.app]
57
59
command = "deno run -A app/build/preprocessor.ts"
+2
docs/src/SUMMARY.md
+2
docs/src/SUMMARY.md
+7
-6
docs/src/link-forever/features.md
+7
-6
docs/src/link-forever/features.md
···
24
24
25
25
> [!TIP]
26
26
>
27
-
> Linking by path is cool! Not only is it well-supported by GitHub, but editors like VS
28
-
> Code also provide smart features like [path completions][path-completions] and [link
29
-
> validation][link-validation].
27
+
> Linking by path is cool! Not only is it [well-supported by
28
+
> GitHub][github-relative-links], but editors like VS Code also provide smart features
29
+
> like [path completions][path-completions] and [link validation][link-validation].
30
30
31
31
URL fragments are preserved:
32
32
···
56
56
> are supported, thanks to the [`gix_url`] crate.
57
57
58
58
If you use Git but not GitHub, you can configure a custom URL pattern using the
59
-
[`url-pattern`](configuration.md#url-pattern) option. For example:
59
+
[`repo-url-template`](configuration.md#repo-url-template) option. For example:
60
60
61
61
```toml
62
62
[preprocessor.link-forever]
63
-
url-pattern = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"
63
+
repo-url-template = "https://gitlab.haskell.org/ghc/ghc/-/tree/{ref}/{path}"
64
64
```
65
65
66
66
## Link validation
···
86
86
87
87
<!-- prettier-ignore-start -->
88
88
89
-
[path-completions]: https://code.visualstudio.com/docs/languages/markdown#_path-completions
89
+
[vscode-path-completions]: https://code.visualstudio.com/docs/languages/markdown#_path-completions
90
+
[github-relative-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links
90
91
[link-validation]: https://code.visualstudio.com/docs/languages/markdown#_link-validation
91
92
[mdbook-src-build]: https://rust-lang.github.io/mdBook/guide/creating.html#source-files
92
93
[`output.html.git-repository-url`]: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#html-renderer-options
+13
docs/src/link-forever/known-issues.md
+13
docs/src/link-forever/known-issues.md
···
1
+
# Known issues
2
+
3
+
## Working with `{{#include}}`
4
+
5
+
Linking by relative paths may not make sense when the links are in files that are
6
+
embedded using mdBook's `{{#include}}` directive.
7
+
8
+
See [Working with `{{#include}}`](working-with-include.md) for some possible
9
+
workarounds.
10
+
11
+
## Links in HTML
12
+
13
+
Links in HTML (`href` and `src`) are currently neither transformed nor checked.
docs/src/link-forever/media/error-reporting-canonical-urls.png
docs/src/link-forever/media/error-reporting-canonical-urls.png
This is a binary file and will not be displayed.
+85
docs/src/link-forever/working-with-include.md
+85
docs/src/link-forever/working-with-include.md
···
1
+
# Working with `{{#include}}`
2
+
3
+
mdBook provides an [`{{#include}}` directive][mdbook-include] that you can embed files
4
+
in book pages. If the embedded content also contains path-based links, then some extra
5
+
care may be needed:
6
+
7
+
- The preprocessor does not resolve links relative to the file being included because it
8
+
does not have enough information. In this case, relative paths could be valid for the
9
+
source file (and therefore valid for e.g. GitHub) but invalid for the book.
10
+
11
+
- In some cases, you cannot use path-based links and you have to use full URLs. This
12
+
could be because the included file is also intended for platforms that don't support
13
+
paths as links.
14
+
15
+
This page describes some workarounds for linking in included files.
16
+
17
+
- [Using absolute paths](#using-absolute-paths)
18
+
- [Using URLs to link to book pages](#using-urls-to-link-to-book-pages)
19
+
20
+
## Using absolute paths
21
+
22
+
To use paths as links in included content, you can use absolute paths that start with a
23
+
`/`.
24
+
25
+
Paths that start with a `/` are resolved relative to the root of your repository. This
26
+
is supported both in [VS Code][vscode-path-completions] and on
27
+
[GitHub][github-relative-links], for example.
28
+
29
+
> ```md
30
+
> Front page of this book is actually from
31
+
> [the crate README](/crates/mdbookkit/README.md).
32
+
> ```
33
+
>
34
+
> Front page of this book is actually from
35
+
> [the crate README](/crates/mdbookkit/README.md).
36
+
37
+
## Using URLs to link to book pages
38
+
39
+
You may be in a situation where you have to use full URLs to link to your book rather
40
+
than relying on paths.
41
+
42
+
> An example (that this project encountered) is including files that are also intended
43
+
> for displaying on [crates.io][cargo-readme].
44
+
>
45
+
> In this case, linking to book pages would require writing down full URLs to the
46
+
> deployed book, since other platforms like crates.io will not convert path-based `.md`
47
+
> links to URLs.
48
+
49
+
To mitigate this, you can use the [`book-url`](configuration.md#book-url) option, and
50
+
then use full URLs in the included content.
51
+
52
+
In your `book.toml`, in the `[preprocessor.link-forever]` table, specify the URL prefix
53
+
at which you will deploy your book:
54
+
55
+
```toml
56
+
[preprocessor.link-forever]
57
+
book-url = "https://example.org/"
58
+
```
59
+
60
+
Then, in Markdown, you may use full URLs, for example:
61
+
62
+
> ```md
63
+
> For a list of the crate's features, see [Feature flags](https://example.org/features).
64
+
> ```
65
+
>
66
+
> For a list of the crate's features, see [Feature flags](https://example.org/features).
67
+
68
+
Specifying `book-url` enables the preprocessor to check URLs to your book against local
69
+
paths. If a URL does not have a corresponding `.md` file under your book's `src/`
70
+
directory, the preprocessor will warn you:
71
+
72
+
<figure>
73
+
74
+
75
+
76
+
</figure>
77
+
78
+
<!-- prettier-ignore-start -->
79
+
80
+
[mdbook-include]: https://rust-lang.github.io/mdBook/format/mdbook.html#including-files
81
+
[vscode-path-completions]: https://code.visualstudio.com/docs/languages/markdown#_path-completions
82
+
[github-relative-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links
83
+
[cargo-readme]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-readme-field
84
+
85
+
<!-- prettier-ignore-end -->
+2
-1
docs/src/rustdoc-link.md
+2
-1
docs/src/rustdoc-link.md
···
40
40
41
41
For **writing documentation** —
42
42
43
-
- To know more about how the preprocessor is resolving items into links, see
43
+
- To know more about how the preprocessor is resolving items into links, including
44
+
[feature-gated items](rustdoc-link/name-resolution.md#feature-gated-items), see
44
45
[Name resolution](rustdoc-link/name-resolution.md).
45
46
- To know how to link to other types of items like
46
47
[functions, macros](rustdoc-link/supported-syntax.md#functions-and-macros), and
+5
docs/src/rustdoc-link/caching.md
+5
docs/src/rustdoc-link/caching.md
···
50
50
51
51
## How it works
52
52
53
+
> [!NOTE]
54
+
>
55
+
> The following are implementation details. See
56
+
> [rustdoc_link/cache.rs](/crates/mdbookkit/src/bin/rustdoc_link/cache.rs).
57
+
53
58
The effectiveness of this mechanism is based on the following assumptions:
54
59
55
60
- Most of the changes made during authoring don't actually involve item links.
+3
docs/src/rustdoc-link/getting-started.md
+3
docs/src/rustdoc-link/getting-started.md
···
19
19
cargo install mdbookkit --features rustdoc-link
20
20
```
21
21
22
+
Or you can grab precompiled binaries from [GitHub releases][gh-releases].
23
+
22
24
## Configure
23
25
24
26
Configure your `book.toml` to use it as a [preprocessor]:
···
88
90
[ra-install]: https://rust-analyzer.github.io/book/rust_analyzer_binary.html
89
91
[open-docs]: https://rust-analyzer.github.io/book/features.html#open-docs
90
92
[ra-extension]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer
93
+
[gh-releases]: https://github.com/tonywu6/mdbookkit/releases
91
94
92
95
<!-- prettier-ignore-end -->
+2
-1
docs/src/rustdoc-link/name-resolution.md
+2
-1
docs/src/rustdoc-link/name-resolution.md
···
126
126
127
127
> [!NOTE]
128
128
>
129
-
> The following are implementation details.
129
+
> The following are implementation details. See
130
+
> [rustdoc_link/mod.rs](/crates/mdbookkit/src/bin/rustdoc_link/mod.rs).
130
131
131
132
`mdbook-rustdoc-link` parses your book and collects every link that looks like a Rust
132
133
item. Then it synthesizes a Rust function that spells out all the items, which looks
+16
-6
utils/clap-reflect/src/main.rs
+16
-6
utils/clap-reflect/src/main.rs
···
1
+
//! Derive Markdown documentation from [`clap::Parser`]s.
2
+
//!
3
+
//! Functions as an mdBook preprocessor that replaces
4
+
//! `<cmd-option>(autogenerated)</cmd-option>` with said documentation.
5
+
//!
6
+
//! - [mdbookkit::bin::rustdoc_link::env::Config]
7
+
//! - [mdbookkit::bin::link_forever::Config]
8
+
1
9
use std::io::{Read, Write};
2
10
3
11
use anyhow::Result;
···
6
14
use minijinja::render;
7
15
use serde::Serialize;
8
16
9
-
use tap::Pipe;
17
+
use tap::{Pipe, Tap};
10
18
11
19
#[derive(Parser, Debug, Clone)]
12
20
struct Program {
···
81
89
key: String,
82
90
help: String,
83
91
description: String,
84
-
type_id: Option<String>,
92
+
type_id: Option<(String, String)>,
85
93
default: Option<String>,
86
94
choices: Vec<(String, String)>,
87
95
}
···
186
194
<th style="text-align: left;">Type</th>
187
195
<td>
188
196
189
-
[`{{ option.type_id }}`]
197
+
[`{{ option.type_id[0] }}`][{{ option.type_id[1] }}]
190
198
191
199
</td>
192
200
</tr>
···
218
226
let type_id = if cfg!(debug_assertions) {
219
227
let ty = format!("{:?}", opt.get_value_parser().type_id())
220
228
.replace("alloc::string::", "");
229
+
let name = ty.split("::").last().unwrap();
221
230
if matches!(action, ArgAction::Append) {
222
-
Some(format!("Vec<{ty}>"))
231
+
Some((format!("Vec<{name}>"), format!("Vec<{ty}>")))
223
232
} else {
224
-
Some(ty)
233
+
Some((name.to_owned(), ty))
225
234
}
226
235
} else {
227
236
None
···
263
272
choices,
264
273
}
265
274
})
266
-
.collect::<Vec<_>>();
275
+
.collect::<Vec<_>>()
276
+
.tap_mut(|opts| opts.sort_by(|a, b| a.key.cmp(&b.key)));
267
277
268
278
Ok(render!(template, options))
269
279
}
+6
utils/rust-analyzer/src/main.rs
+6
utils/rust-analyzer/src/main.rs
···
1
+
//! Download a copy of rust-analyzer to /.bin to use in testing.
2
+
//!
3
+
//! Version can be controlled with the `RA_VERSION` environment variable.
4
+
1
5
use std::{
2
6
fs, io,
3
7
os::unix::fs::PermissionsExt,
···
156
160
}
157
161
}
158
162
163
+
/// Preprocessor to replace `<ra-version>(version)</ra-version>` with the currently
164
+
/// used RA version. Used in docs.
159
165
#[cfg(feature = "ra-version")]
160
166
mod ra_version {
161
167
use std::io::{Read, Write};