{"id":13478068,"url":"https://github.com/Michael-F-Bryan/mdbook-linkcheck","last_synced_at":"2025-03-27T07:30:44.143Z","repository":{"id":28600471,"uuid":"117332495","full_name":"Michael-F-Bryan/mdbook-linkcheck","owner":"Michael-F-Bryan","description":"A backend for `mdbook` which will check your links for you.","archived":false,"fork":false,"pushed_at":"2024-08-15T13:00:47.000Z","size":23220,"stargazers_count":152,"open_issues_count":32,"forks_count":30,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-19T16:46:56.635Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://michael-f-bryan.github.io/mdbook-linkcheck/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Michael-F-Bryan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-13T09:51:57.000Z","updated_at":"2025-03-15T19:52:01.000Z","dependencies_parsed_at":"2024-01-16T06:18:36.029Z","dependency_job_id":"f5189521-2332-4e98-b1fb-1e27fbae8e76","html_url":"https://github.com/Michael-F-Bryan/mdbook-linkcheck","commit_stats":{"total_commits":213,"total_committers":12,"mean_commits":17.75,"dds":0.09859154929577463,"last_synced_commit":"bed5ebbae325d41bdccec382ecbe30f795738ca2"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Michael-F-Bryan%2Fmdbook-linkcheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Michael-F-Bryan%2Fmdbook-linkcheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Michael-F-Bryan%2Fmdbook-linkcheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Michael-F-Bryan%2Fmdbook-linkcheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Michael-F-Bryan","download_url":"https://codeload.github.com/Michael-F-Bryan/mdbook-linkcheck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245802216,"owners_count":20674611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:01:52.032Z","updated_at":"2025-03-27T07:30:43.687Z","avatar_url":"https://github.com/Michael-F-Bryan.png","language":"Rust","funding_links":[],"categories":["Rust","others","Applications","Documentation \u0026 Writing"],"sub_categories":[],"readme":"# MDBook Link-Check\n\n[![Continuous integration](https://github.com/Michael-F-Bryan/mdbook-linkcheck/workflows/Continuous%20integration/badge.svg?branch=master)](https://github.com/Michael-F-Bryan/mdbook-linkcheck/actions)\n[![Crates.io](https://img.shields.io/crates/v/mdbook-linkcheck.svg)](https://crates.io/crates/mdbook-linkcheck)\n[![Docs.rs](https://docs.rs/mdbook-linkcheck/badge.svg)](https://docs.rs/mdbook-linkcheck/)\n[![license](https://img.shields.io/github/license/michael-f-bryan/mdbook-linkcheck.svg)](https://github.com/Michael-F-Bryan/mdbook-linkcheck/blob/master/LICENSE)\n\nA backend for `mdbook` which will check your links for you. For use alongside\nthe built-in HTML renderer.\n\n## Getting Started\n\nFirst you'll need to install `mdbook-linkcheck`.\n\n```\ncargo install mdbook-linkcheck\n```\n\nIf you don't want to install from source (which often takes a while) you can\ngrab an executable from [GitHub Releases][releases] or use this line of\n`curl` to download a release bundle and install it in the `./mdbook-linkcheck`\ndirectory:\n\n```console\nmkdir -p mdbook-linkcheck \u0026\u0026 cd \"$_\" \u0026\u0026 \\\n  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 \u0026\u0026 \\\n  unzip \"$_\" \u0026\u0026 \\\n  chmod +x mdbook-linkcheck \u0026\u0026 \\\n  export PATH=$PWD:$PATH \u0026\u0026 \\\n  cd ..\n```\n\n(note: you may need to replace the `x86_64-unknown-linux-gnu` with your\nplatform's target triple)\n\nNext you'll need to update your `book.toml` to let `mdbook` know it needs to\nuse `mdbook-linkcheck` as a backend.\n\n```toml\n[book]\ntitle = \"My Awesome Book\"\nauthors = [\"Michael-F-Bryan\"]\n\n[output.html]\n\n[output.linkcheck]\n```\n\nAnd finally you should be able to run `mdbook build` like normal and everything\nshould *Just Work*.\n\n```\n$ mdbook build\n```\n\n\u003e **Note:** When multiple `[output]` items are specified, `mdbook` tries to\n\u003e ensure that each `[output]` gets its own sub-directory within the `build-dir`\n\u003e (`book/` by default).\n\u003e\n\u003e That means if you go from only having the HTML renderer enabled to enabling\n\u003e both HTML and the linkchecker, your HTML will be placed in `book/html/`\n\u003e instead of just `book/` like before.\n\n## Configuration\n\nThe link checker's behaviour can be configured by setting options under the\n`output.linkcheck` table in your `book.toml`.\n\n```toml\n...\n\n[output.linkcheck]\n# Should we check links on the internet? Enabling this option adds a\n# non-negligible performance impact\nfollow-web-links = false\n\n# Are we allowed to link to files outside of the book's root directory? This\n# may help prevent linking to sensitive files (e.g. \"../../../../etc/shadow\")\ntraverse-parent-directories = false\n\n# If necessary, you can exclude one or more links from being checked with a\n# list of regular expressions. The regex will be applied to the link href (i.e.\n# the `./index.html` in `[some page](./index.html)`) so it can be used to\n# ignore both web and filesystem links.\n#\n# Hint: you can use TOML's raw strings (single quote) to avoid needing to\n# escape things twice.\nexclude = [ 'google\\.com' ]\n\n# The User-Agent to use when sending web requests\nuser-agent = \"mdbook-linkcheck-0.4.0\"\n\n# The number of seconds a cached result is valid for (12 hrs by default)\ncache-timeout = 43200\n\n# How should warnings be treated?\n#\n# - \"warn\" will emit warning messages\n# - \"error\" treats all warnings as errors, failing the linkcheck\n# - \"ignore\" will ignore warnings, suppressing diagnostic messages and allowing\n#   the linkcheck to continuing\nwarning-policy = \"warn\"\n\n# Extra HTTP headers that must be send to certain web sites\n# in order to link check to succeed.\n#\n# This is a dictionary (map), with keys being regexes\n# matching a set of web sites, and values being an array of\n# the headers.\n[output.linkcheck.http-headers]\n# Any hyperlink that contains this regexp will be sent\n# the \"Accept: text/html\" header\n'crates\\.io' = [\"Accept: text/html\"]\n\n# mdbook-linkcheck will interpolate environment variables into your header via\n# $IDENT.\n#\n# If this is not what you want you must escape the `$` symbol, like `\\$TOKEN`.\n# `\\` itself can also be escaped via `\\\\`.\n#\n# Note: If interpolation fails, the header will be skipped and the failure will\n# be logged. This can be useful if a particular header isn't always necessary,\n# but may be helpful (e.g. when working with rate limiting).\n'website\\.com' = [\"Authorization: Basic $TOKEN\"]\n```\n\n## Continuous Integration\n\nIncorporating `mdbook-linkcheck` into your CI system should be straightforward\nif you are already [using `mdbook` to generate documentation][mdbook-ci].\n\nFor those using GitLab's built-in CI:\n\n```yaml\ngenerate-book:\n  stage: build\n  image:\n    name: michaelfbryan/mdbook-docker-image:latest\n    entrypoint: [\"\"]\n  script:\n    - mdbook build $BOOK_DIR\n  artifacts:\n    paths:\n      - $BOOK_DIR/book/html\n    # make sure GitLab doesn't accidentally keep every book you ever generate\n    # indefinitely\n    expire_in: 1 week\n\npages:\n  image: busybox:latest\n  stage: deploy\n  dependencies:\n    - generate-book\n  script:\n    - cp -r $BOOK_DIR/book/html public\n  artifacts:\n    paths:\n    - public\n  only:\n    - master\n```\n\nThe [michaelfbryan/mdbook-docker-image][image] docker image is also available\non Docker hub and comes with the latest version of `mdbook` and\n`mdbook-linkcheck` pre-installed.\n\n[releases]: https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases\n[mdbook-ci]: https://rust-lang.github.io/mdBook/continuous-integration.html\n[Michael-F-Bryan]: https://github.com/Michael-F-Bryan\n[image]: https://hub.docker.com/r/michaelfbryan/mdbook-docker-image\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichael-F-Bryan%2Fmdbook-linkcheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMichael-F-Bryan%2Fmdbook-linkcheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichael-F-Bryan%2Fmdbook-linkcheck/lists"}