toolkit for mdBook [mirror of my GitHub repo]
docs.tonywu.dev/mdbookkit/
permalinks
rust-analyzer
mdbook
docs: update docs (WIP)
+106
-120
+1
-1
crates/mdbook-rustdoc-links/src/tests/snaps/index.snap
+1
-1
crates/mdbook-rustdoc-links/src/tests/snaps/index.snap
+1
-1
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.snap
+1
-1
crates/mdbook-rustdoc-links/src/tests/snaps/known-issues.snap
···
7
7
8
8
## Performance
9
9
10
-
`mdbook-rustdoc-links` itself doesn't need much processing power, but it invokes
10
+
The preprocessor itself doesn't need much processing power, but it invokes
11
11
rust-analyzer, which does a full scan of your workspace. The larger your workspace is,
12
12
the longer mdBook will have to wait for the preprocessor. This is the source of the
13
13
majority of the run time.
+3
-5
docs/src/permalinks/configuration.md
+3
-5
docs/src/permalinks/configuration.md
···
2
2
3
3
This page lists all options for the preprocessor.
4
4
5
-
For use in `book.toml`, configure under the `[preprocessor.link-forever]` table using
6
-
the keys below, for example:
5
+
Configure options in the `[preprocessor.permalinks]` table using the keys below, for
6
+
example:
7
7
8
8
```toml
9
-
[preprocessor.link-forever]
9
+
[preprocessor.permalinks]
10
10
always-link = [".rs"]
11
11
```
12
-
13
-
<link-forever-options>(autogenerated)</link-forever-options>
+11
-51
docs/src/permalinks/continuous-integration.md
+11
-51
docs/src/permalinks/continuous-integration.md
···
1
1
# Continuous integration
2
2
3
-
This page gives information and tips for using `mdbook-link-forever` in a continuous
4
-
integration (CI) environment.
5
-
6
-
The preprocessor behaves differently in terms of logging, error handling, etc., when it
7
-
detects it is running in CI.
8
-
9
-
<details class="toc" open>
10
-
<summary>Sections</summary>
11
-
12
-
- [Detecting CI](#detecting-ci)
13
-
- [Linking to Git tags](#linking-to-git-tags)
14
-
- [Logging](#logging)
15
-
- [Error handling](#error-handling)
16
-
17
-
</details>
3
+
The preprocessor optimizes some behaviors for continuous integration (CI) environments,
4
+
in terms of error handling, logging, etc.
18
5
19
6
## Detecting CI
20
7
21
-
To determine whether it is running in CI, the preprocessor honors the `CI` environment
22
-
variable. Specifically:
23
-
24
-
- If `CI` is set to `"true"`, then it is considered in CI[^ci-true];
25
-
- Otherwise, it is considered not in CI.
26
-
27
-
Most major CI/CD services, such as [GitHub Actions][github-actions-ci] and [GitLab
28
-
CI/CD][gitlab-ci], automatically configure this variable for you.
8
+
{{#include ../snippets/detecting-ci.md}}
29
9
30
10
## Linking to Git tags
31
11
32
-
The preprocessor supports both tags and commit SHAs when generating permalinks. The use
33
-
of tags is contingent on HEAD being tagged in local Git at build time. You should ensure
34
-
that tags are present when building in CI, or the preprocessor will fallback to using
35
-
the full SHA (it would still be a permalink, just that it will be more verbose).
12
+
The preprocessor supports both tags and commit hashes when generating permalinks. **The
13
+
use of tags is contingent on HEAD being tagged in local Git at build time.**
14
+
15
+
You should ensure that tags are present locally when building in CI, otherwise the
16
+
preprocessor will fallback to using the full commit hash. The resulting permalinks will
17
+
function the same, but they will be more verbose.
36
18
37
19
For example, in [GitHub Actions][actions/checkout], you can use:
38
20
···
46
28
47
29
## Logging
48
30
49
-
By default, the preprocessor shows a progress spinner when it is running.
50
-
51
-
When running in CI, progress is instead printed as logs (using [log] and
52
-
[env_logger])[^stderr].
53
-
54
-
You can control logging levels using the [`RUST_LOG`] environment variable.
31
+
{{#include ../snippets/logging.md}}
55
32
56
33
## Error handling
57
34
58
-
By default, when the preprocessor encounters any non-fatal issues, such as when a link
59
-
fails to resolve, it prints them as warnings but continues to run. This is so that your
60
-
book continues to build via `mdbook serve` while you make edits.
61
-
62
-
When running in CI, all such warnings are promoted to errors. The preprocessor will exit
63
-
with a non-zero status code when there are warnings, which will fail your build. This
64
-
prevents outdated or incorrect links from being accidentally deployed.
65
-
66
-
You can explicitly control this behavior using the
67
-
[`fail-on-warnings`](configuration.md#fail-on-warnings) option.
68
-
69
-
[^ci-true]:
70
-
Specifically, when `CI` is anything other than `""`, `"0"`, or `"false"`. The logic
71
-
is encapsulated in the [`is_ci`][crate::error::is_ci] function.
72
-
73
-
[^stderr]:
74
-
Specifically, when stderr is redirected to something that isn't a terminal, such as
75
-
a file.
35
+
{{#include ../snippets/error-handling.md}}
76
36
77
37
<!-- prettier-ignore-start -->
78
38
+18
-9
docs/src/permalinks/features.md
+18
-9
docs/src/permalinks/features.md
···
22
22
> like [path completions][vscode-path-completions] and [link
23
23
> validation][link-validation].
24
24
25
-
Permalinks are **versioned using the tag name or hash** of the commit from which the
26
-
book was built. Your links remain consistent with their source commit even as content in
27
-
your repository changes over time.
28
-
29
-
URL fragments are preserved. For example, you may use fragments to link to specific
25
+
**URL fragments** are preserved. For example, you may use fragments to link to specific
30
26
lines, if your Git hosting provider supports it:
31
27
32
28
> ```md
···
38
34
> [preprocess its style sheet](../../app/build/build.ts#L13-25).
39
35
40
36
By default, links to files under your book's `src/` directory are not converted, since
41
-
mdBook already [copies them to build output][mdbook-src-build], but this is configurable
37
+
mdBook already [copies them to build output][mdbook-src-build]. This is configurable
42
38
using the [`always-link`](configuration.md#always-link) option.
39
+
40
+
## Versioning
41
+
42
+
Permalinks are **versioned using the tag name or hash** of the commit from which the
43
+
book was built. Your links remain consistent with their source commit even as content in
44
+
your repository changes over time.
43
45
44
46
## Repo URL auto-discovery
45
47
···
54
56
> For Git remotes, both HTTP URLs and "scp-like" URIs (`git@github.com:org/repo.git`)
55
57
> are supported.
56
58
59
+
Currently, the preprocessor automatically uses repo URLs from the following providers:
60
+
61
+
- GitHub, `https://github.com/*`
62
+
57
63
Alternatively, you may configure a custom URL format using the
58
64
[`repo-url-template`](configuration.md#repo-url-template) option.
59
65
···
65
71
- a `raw` URL that directly serves the file's content, suitable for embedding or
66
72
downloading
67
73
68
-
The preprocessor detects whether a path is used within a clickable link or an image and
69
-
selects the most appropriate type of URL to use. For example, the following snippet
70
-
creates an image wrapped in a clickable link which opens the image's page on GitHub:
74
+
The preprocessor detects the context in which a link appears and selects the most
75
+
appropriate type of URL to use: `tree` if it is a clickable link, or `raw` if it is for
76
+
an image.
77
+
78
+
For example, the following snippet creates an image wrapped in a clickable link which
79
+
opens the image's page on GitHub:
71
80
72
81
> ```md
73
82
> [![Minato City][minato-city]][minato-city]
+1
-1
docs/src/permalinks/getting-started.md
+1
-1
docs/src/permalinks/getting-started.md
···
47
47
48
48
## Next steps
49
49
50
+
- See the list of [features](features.md) in detail.
50
51
- Check out [available configuration options](configuration.md).
51
-
<!-- TODO: including options to ... -->
52
52
- Learn about [known issues and limitations](known-issues.md).
53
53
54
54
<!-- prettier-ignore-start -->
+7
-1
docs/src/permalinks/index.md
+7
-1
docs/src/permalinks/index.md
···
20
20
21
21
## Overview
22
22
23
-
<!-- TODO: -->
23
+
- Create [permalinks](features.md#permalinks) by file path.
24
+
- Links are [pinned to the tag or commit](features.md#versioning) that is checked out at
25
+
build time.
26
+
- Links are [validated](features.md#link-validation) during build. Receive warnings when
27
+
a linked file become missing.
28
+
- Repository URLs are [autoconfigured for GitHub](features.md#repo-url-auto-discovery),
29
+
or you can use a [custom URL scheme](configuration.md#repo-url-template).
24
30
25
31
## License
26
32
+5
-5
docs/src/permalinks/known-issues.md
+5
-5
docs/src/permalinks/known-issues.md
···
2
2
3
3
## Working with `{{#include}}`
4
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.
5
+
Linking by relative paths may not work when the links are in files that are embedded
6
+
using mdBook's `{{#include}}` directive.
7
7
8
-
See [Working with `{{#include}}`](working-with-include.md) for some possible
9
-
workarounds.
8
+
See [More ways to link](more-ways-to-link.md) for some possible workarounds.
10
9
11
10
## Links in HTML
12
11
13
-
Links in HTML (`href` and `src`) are currently neither transformed nor checked.
12
+
URLs in HTML (`href` and `src`) are currently unsupported. They are neither checked nor
13
+
transformed.
+7
-7
docs/src/permalinks/more-ways-to-link.md
+7
-7
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
-
The preprocessor supports some alternative link formats for such scenarios.
11
+
For such cases, the preprocessor supports some alternative link formats.
12
12
13
13
```mermaid
14
14
stateDiagram-v2
···
38
38
39
39
> For example, if `chapters/1.md` includes `shared/info.md`, and `shared/info.md`
40
40
> contains a link to `./image.png` (i.e. `shared/image.png`), then the preprocessor can
41
-
> only resolve `./image.png` starting from `chapters/1.md` (i.e. `chapters/image.png`),
42
-
> which is incorrect.
41
+
> only resolve `./image.png` starting from `chapters/1.md`, which becomes
42
+
> `chapters/image.png`, which is incorrect.
43
43
44
44
Instead of using relative paths, you may use paths that **start with a `/`**. Paths that
45
45
start with a `/` are resolved **relative to the root of your repository**:
···
55
55
## Using URLs
56
56
57
57
In some situations, you cannot link using paths, and must fallback to full URLs. For
58
-
example, you would like to reuse your package's `README.md` as your book's home page,
58
+
example, you may want to reuse your package's `README.md` for your book's home page,
59
59
where the `README.md` is also published to crates.io, where path-based links will become
60
60
invalid.
61
61
···
83
83
84
84
### Using URLs to your book
85
85
86
-
Finally, you can link to a page or file within your book using full URLs and the
87
-
preprocessor will validate that the corresponding file is accessible.
86
+
You can link to a page or file within your book using full URLs and the preprocessor
87
+
will validate that the corresponding file is accessible.
88
88
89
89
To enable validation of book URLs, you must specify the URL prefix at which you will
90
90
deploy your book via the [`book-url`](configuration.md#book-url) option:
91
91
92
92
```toml
93
93
[preprocessor.permalinks]
94
-
book-url = "https://example.org/"
94
+
book-url = "https://example.org/book/"
95
95
```
96
96
97
97
For each link that begins with this prefix, the preprocessor tests whether a matching
+3
-37
docs/src/rustdoc-links/continuous-integration.md
+3
-37
docs/src/rustdoc-links/continuous-integration.md
···
5
5
6
6
## Detecting CI
7
7
8
-
To determine whether it is running in a CI environment, the preprocessor honors the `CI`
9
-
environment variable. Specifically:
10
-
11
-
- If `CI` is set to `"true"`, then it is considered in CI[^ci-true];
12
-
- Otherwise, it is considered not in CI.
13
-
14
-
Providers such as [GitHub Actions][github-actions-ci] and [GitLab CI/CD][gitlab-ci] have
15
-
this variable configured by default.
8
+
{{#include ../snippets/detecting-ci.md}}
16
9
17
10
## Installing rust-analyzer
18
11
···
35
28
36
29
## Logging
37
30
38
-
<!-- TODO: -->
39
-
40
-
By default, the preprocessor shows a progress spinner when it is running.
41
-
42
-
When running in CI, progress is instead printed as logs (using [log] and
43
-
[env_logger])[^stderr].
44
-
45
-
You can control logging levels using the [`RUST_LOG`] environment variable.
31
+
{{#include ../snippets/logging.md}}
46
32
47
33
## Error handling
48
34
49
-
When running locally, when the preprocessor encounters any non-fatal issues, such as
50
-
when a link fails to resolve, it prints them as warnings but continues to run. This is
51
-
so that your book continues to build via `mdbook serve` while you make edits.
52
-
53
-
**When running in CI, all such warnings are promoted to errors by default.** The
54
-
preprocessor will exit with a non-zero status code which will fail your build. This is
55
-
to prevent outdated or incorrect links from being accidentally deployed.
56
-
57
-
You can explicitly control this behavior using the
58
-
[`fail-on-warnings`](configuration.md#fail-on-warnings) option.
35
+
{{#include ../snippets/error-handling.md}}
59
36
60
37
[^ra-on-path]:
61
38
You may alternatively specify a command to use for rust-analyzer via the
62
39
[`rust-analyzer`](configuration.md#rust-analyzer) configuration option.
63
40
64
-
[^ci-true]:
65
-
Specifically, when `CI` is anything other than `""`, `"0"`, or `"false"`. The logic
66
-
is encapsulated in the [`is_ci`][crate::error::is_ci] function.
67
-
68
-
[^stderr]:
69
-
Specifically, when stderr is redirected to something that isn't a terminal, such as
70
-
a file.
71
-
72
41
<!-- prettier-ignore-start -->
73
42
74
-
[`RUST_LOG`]: https://docs.rs/env_logger/latest/env_logger/#enabling-logging
75
43
[dtolnay/rust-toolchain]: https://github.com/dtolnay/rust-toolchain
76
-
[github-actions-ci]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
77
-
[gitlab-ci]: https://docs.gitlab.com/ci/variables/predefined_variables/
78
44
[rustup-ra]: https://rust-analyzer.github.io/book/rust_analyzer_binary.html#rustup
79
45
80
46
<!-- prettier-ignore-end -->
+1
-1
docs/src/rustdoc-links/index.md
+1
-1
docs/src/rustdoc-links/index.md
+1
-1
docs/src/rustdoc-links/known-issues.md
+1
-1
docs/src/rustdoc-links/known-issues.md
···
2
2
3
3
## Performance
4
4
5
-
`mdbook-rustdoc-links` itself doesn't need much processing power, but it invokes
5
+
The preprocessor itself doesn't need much processing power, but it invokes
6
6
rust-analyzer, which does a full scan of your workspace. The larger your workspace is,
7
7
the longer mdBook will have to wait for the preprocessor. This is the source of the
8
8
majority of the run time.
+19
docs/src/snippets/detecting-ci.md
+19
docs/src/snippets/detecting-ci.md
···
1
+
To determine whether it is running in a CI environment, the preprocessor honors the `CI`
2
+
environment variable. Specifically:
3
+
4
+
- If `CI` is set to `"true"`, then it is considered in CI[^ci-true];
5
+
- Otherwise, it is considered not in CI.
6
+
7
+
Providers such as [GitHub Actions][github-actions-ci] and [GitLab CI/CD][gitlab-ci] have
8
+
this variable configured by default.
9
+
10
+
[^ci-true]:
11
+
Specifically, when `CI` is anything other than `""`, `"0"`, or `"false"`. The logic
12
+
is encapsulated in the [`is_ci`][crate::error::is_ci] function.
13
+
14
+
<!-- prettier-ignore-start -->
15
+
16
+
[github-actions-ci]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
17
+
[gitlab-ci]: https://docs.gitlab.com/ci/variables/predefined_variables/
18
+
19
+
<!-- prettier-ignore-end -->
+10
docs/src/snippets/error-handling.md
+10
docs/src/snippets/error-handling.md
···
1
+
When running locally, when the preprocessor encounters any non-fatal issues, such as
2
+
when a link fails to resolve, it prints them as warnings but continues to run. This is
3
+
so that your book continues to build via `mdbook serve` while you make edits.
4
+
5
+
**When running in CI, all such warnings are promoted to errors by default.** The
6
+
preprocessor will exit with a non-zero status code which will fail your build. This is
7
+
to prevent outdated or incorrect links from being accidentally deployed.
8
+
9
+
You can explicitly control this behavior using the
10
+
[`fail-on-warnings`](configuration.md#fail-on-warnings) option.
+18
docs/src/snippets/logging.md
+18
docs/src/snippets/logging.md
···
1
+
<!-- TODO: -->
2
+
3
+
By default, the preprocessor shows a progress spinner when it is running.
4
+
5
+
When running in CI, progress is instead printed as logs (using [log] and
6
+
[env_logger])[^stderr].
7
+
8
+
You can control logging levels using the [`RUST_LOG`] environment variable.
9
+
10
+
[^stderr]:
11
+
Specifically, when stderr is redirected to something that isn't a terminal, such as
12
+
a file.
13
+
14
+
<!-- prettier-ignore-start -->
15
+
16
+
[`RUST_LOG`]: https://docs.rs/env_logger/latest/env_logger/#enabling-logging
17
+
18
+
<!-- prettier-ignore-end -->