mdbook-permalinks 3.0.0

mdBook preprocessor to generate Git permalinks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

<!-- generated by running `just docs readme` -->

# mdbook-permalinks

<div class="hidden">

**For best results, view this page at [https://docs.tonywu.dev/mdbookkit/permalinks](https://docs.tonywu.dev/mdbookkit/).**

</div>

Permalinks in [mdBook]!

With this [preprocessor], you can easily link to any file in your Git repository in your
mdBook documentation, without having to hard-code URLs or worry about broken links.

You simply write ...

```md
Here is a link to the project's [Cargo.toml](/Cargo.toml).
```

... and you will get:

<figure class="fig-text">

Here is a link to the project's [Cargo.toml](https://github.com/tonywu6/mdbookkit/tree/88431989183b48e8c052751b39f547e8824ea677/Cargo.toml).

</figure>

## Overview

Follow the [quickstart tutorial](https://docs.tonywu.dev/mdbookkit/getting-started.html) to try out the preprocessor!

Feature highlights:

- [Use file paths as links](https://docs.tonywu.dev/mdbookkit/getting-started.html#linking-by-paths). The preprocessor
  converts them to links to your Git repository.

- Links are anchored to the Git commit at the time your book is built.

- Supports repositories on GitHub, Codeberg, and Tangled out of the box, but you can
  also
  [define your own permalink format](https://docs.tonywu.dev/mdbookkit/how-to/remote-url.html#using-a-custom-permalink-format).

- Use permalinks to display [images](https://docs.tonywu.dev/mdbookkit/getting-started.html#images) and
  [media files](https://docs.tonywu.dev/mdbookkit/getting-started.html#html-links).

- [Get warnings](https://docs.tonywu.dev/mdbookkit/getting-started.html#check) when links become broken.

<figure>


<svg width="740px" height="200px" xmlns="http://www.w3.org/2000/svg">&#10;  <style>&#10;    .fg { fill: #B2B2B2 }&#10;    .bg { fill: #1A1A1A }&#10;    .fg-bright-blue { fill: #5CADF1 }&#10;    .fg-yellow { fill: #D19A66 }&#10;    .container {&#10;      padding: 0 10px;&#10;      line-height: 18px;&#10;    }&#10;    .bold { font-weight: bold; }&#10;    tspan {&#10;      font: 14px Menlo, Roboto Mono, Ubuntu Mono, Liberation Mono, Consolas, ui-monospace, monospace;&#10;      white-space: pre;&#10;      line-height: 18px;&#10;    }&#10;  </style>&#10;&#10;  <rect width="100%" height="100%" y="0"  class="bg" />&#10;&#10;  <text xml:space="preserve" class="container fg">&#10;    <tspan x="10px" y="28px"><tspan class="fg-yellow bold">warning</tspan><tspan class="bold">: broken link to "../nook.toml"</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="46px"><tspan> </tspan><tspan class="fg-bright-blue bold"> ╭▸ </tspan><tspan>src/tutorial.md:1:19</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="64px"><tspan>  </tspan><tspan class="fg-bright-blue bold">│</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="82px"><tspan class="fg-bright-blue bold">1</tspan><tspan> </tspan><tspan class="fg-bright-blue bold">│</tspan><tspan> See &#91;&#96;book.toml&#96;&#93;&#40;</tspan><tspan class="fg-yellow bold">../nook.toml</tspan><tspan>&#41; for more info.</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="100px"><tspan>  </tspan><tspan class="fg-bright-blue bold">│</tspan><tspan>                   </tspan><tspan class="fg-yellow bold">┯━━━━━━━━━━━</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="118px"><tspan>  </tspan><tspan class="fg-bright-blue bold">│</tspan><tspan>                   </tspan><tspan class="fg-bright-blue bold">│</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="136px"><tspan>  </tspan><tspan class="fg-bright-blue bold">│</tspan><tspan>                   </tspan><tspan class="fg-yellow bold">resolves to a path that doesn't exist:</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="154px"><tspan>  </tspan><tspan class="fg-bright-blue bold">╰╴</tspan><tspan>                  </tspan><tspan class="fg-bright-blue bold">"nook.toml"</tspan>&#10;</tspan>&#10;    <tspan x="10px" y="172px">&#10;</tspan>&#10;    <tspan x="10px" y="190px"><tspan class="fg-yellow"> WARN</tspan><tspan> </tspan><tspan class="bold">mdbook-permalinks</tspan><tspan>: finished with warnings</tspan>&#10;</tspan>&#10;  </text>&#10;&#10;</svg>&#10;


<figcaption>

Link rot happens all the time. The preprocessor will tell you about it.

</figcaption>

</figure>

## License

This project is released under the [Apache 2.0 License](https://github.com/tonywu6/mdbookkit/tree/88431989183b48e8c052751b39f547e8824ea677/LICENSE-APACHE.md) and the
[MIT License](https://github.com/tonywu6/mdbookkit/tree/88431989183b48e8c052751b39f547e8824ea677/LICENSE-MIT.md).

<!-- prettier-ignore-start -->
[mdBook]: https://rust-lang.github.io/mdBook/
[preprocessor]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
<!-- prettier-ignore-end -->