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文本处理

Download history 1579/week @ 2024-03-14 1220/week @ 2024-03-21 880/week @ 2024-03-28 1321/week @ 2024-04-04 1300/week @ 2024-04-11 1269/week @ 2024-04-18 1100/week @ 2024-04-25 1286/week @ 2024-05-02 1163/week @ 2024-05-09 1107/week @ 2024-05-16 1043/week @ 2024-05-23 1019/week @ 2024-05-30 1168/week @ 2024-06-06 1303/week @ 2024-06-13 1454/week @ 2024-06-20 967/week @ 2024-06-27

5,050 每月下载量

MIT 许可证

51KB
1K SLoC

MDBook 链接检查

Continuous integration Crates.io Docs.rs license

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 镜像,它预装了最新版本的 mdbookmdbook-linkcheck

依赖项

~18–37MB
~565K SLoC