22 个版本
0.7.7 | 2022 年 10 月 3 日 |
---|---|
0.7.6 | 2021 年 11 月 12 日 |
0.7.5 | 2021 年 9 月 6 日 |
0.7.4 | 2021 年 2 月 26 日 |
0.1.2 | 2018 年 3 月 15 日 |
#222 在 文本处理
5,050 每月下载量
51KB
1K SLoC
MDBook 链接检查
为 mdbook
提供后端,它会为您检查链接。用于与内置的 HTML 渲染器一起使用。
入门指南
首先,您需要安装 mdbook-linkcheck
。
cargo install mdbook-linkcheck
如果您不想从源代码安装(这通常需要很长时间),您可以从 GitHub 发布版 获取可执行文件,或使用以下 curl
命令下载发布包并将其安装到 ./mdbook-linkcheck
目录中
mkdir -p mdbook-linkcheck && cd "$_" && \
curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -o mdbook-linkcheck.zip && \
unzip "$_" && \
chmod +x mdbook-linkcheck && \
export PATH=$PWD:$PATH && \
cd ..
(注意:您可能需要将 x86_64-unknown-linux-gnu
替换为您的平台的目标三元组)
接下来,您需要更新您的 book.toml
文件,以便让 mdbook
知道它需要使用 mdbook-linkcheck
作为后端。
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]
[output.html]
[output.linkcheck]
最后,您应该能够像平常一样运行 mdbook build
,并且一切应该 正常工作。
$ mdbook build
注意:当指定多个
[output]
项目时,mdbook
尝试确保每个[output]
在build-dir
(默认为book/
) 中都有自己的子目录。这意味着如果您从仅启用 HTML 渲染器到同时启用 HTML 和链接检查器,您的 HTML 将被放置在
book/html/
中,而不仅仅是book/
。
配置
可以通过在您的 book.toml
文件中设置 output.linkcheck
表中的选项来配置链接检查器的行为。
...
[output.linkcheck]
# Should we check links on the internet? Enabling this option adds a
# non-negligible performance impact
follow-web-links = false
# Are we allowed to link to files outside of the book's root directory? This
# may help prevent linking to sensitive files (e.g. "../../../../etc/shadow")
traverse-parent-directories = false
# If necessary, you can exclude one or more links from being checked with a
# list of regular expressions. The regex will be applied to the link href (i.e.
# the `./index.html` in `[some page](./index.html)`) so it can be used to
# ignore both web and filesystem links.
#
# Hint: you can use TOML's raw strings (single quote) to avoid needing to
# escape things twice.
exclude = [ 'google\.com' ]
# The User-Agent to use when sending web requests
user-agent = "mdbook-linkcheck-0.4.0"
# The number of seconds a cached result is valid for (12 hrs by default)
cache-timeout = 43200
# How should warnings be treated?
#
# - "warn" will emit warning messages
# - "error" treats all warnings as errors, failing the linkcheck
# - "ignore" will ignore warnings, suppressing diagnostic messages and allowing
# the linkcheck to continuing
warning-policy = "warn"
# Extra HTTP headers that must be send to certain web sites
# in order to link check to succeed.
#
# This is a dictionary (map), with keys being regexes
# matching a set of web sites, and values being an array of
# the headers.
[output.linkcheck.http-headers]
# Any hyperlink that contains this regexp will be sent
# the "Accept: text/html" header
'crates\.io' = ["Accept: text/html"]
# mdbook-linkcheck will interpolate environment variables into your header via
# $IDENT.
#
# If this is not what you want you must escape the `$` symbol, like `\$TOKEN`.
# `\` itself can also be escaped via `\\`.
#
# Note: If interpolation fails, the header will be skipped and the failure will
# be logged. This can be useful if a particular header isn't always necessary,
# but may be helpful (e.g. when working with rate limiting).
'website\.com' = ["Authorization: Basic $TOKEN"]
持续集成
如果已经使用 mdbook
生成文档,那么将 mdbook-linkcheck
集成到 CI 系统应该很简单。
对于使用 GitLab 内置 CI 的用户
generate-book:
stage: build
image:
name: michaelfbryan/mdbook-docker-image:latest
entrypoint: [""]
script:
- mdbook build $BOOK_DIR
artifacts:
paths:
- $BOOK_DIR/book/html
# make sure GitLab doesn't accidentally keep every book you ever generate
# indefinitely
expire_in: 1 week
pages:
image: busybox:latest
stage: deploy
dependencies:
- generate-book
script:
- cp -r $BOOK_DIR/book/html public
artifacts:
paths:
- public
only:
- master
可以在 Docker Hub 上找到 michaelfbryan/mdbook-docker-image Docker 镜像,它预装了最新版本的 mdbook
和 mdbook-linkcheck
。
依赖项
~18–37MB
~565K SLoC