docs: add docs on using Lychee and fix lychee's build

.github/workflows/offline-link-check.yml

@@ -11,9 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+      - run: npm ci
+      - run: npm run build
       - uses: lycheeverse/lychee-action@v2
         with:
           # Only check local files, no network requests
-          args: --config './lychee.toml' --no-progress --offline --root-dir "$GITHUB_WORKSPACE/public/" 'src/content/docs/**/*.md'
+          args: --config './lychee.toml' --no-progress --offline --root-dir "$GITHUB_WORKSPACE/dist/" dist/**/*.html
           # Fail job when lychee returns a non-zero exit code
           fail: true

.gitignore

@@ -35,7 +35,6 @@ dist
 # Astro generated types
 .astro/
 
-
 .lycheecache
 dist/
 

astro.config.mjs

@@ -1,18 +1,22 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeSlug from 'rehype-slug';
 import starlight from '@astrojs/starlight';
 import sitemap from '@astrojs/sitemap';
 import tailwindcss from '@tailwindcss/vite';
 
 export default defineConfig({
   site: 'https://all-contributors.github.io',
   base: '',
+  markdown: {
+    rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
+  },
   output: 'static',
 
   redirects: {
       // Later we can put redirects here if needed
   },
-
   integrations: [
       starlight({
           customCss: [
@@ -65,8 +69,9 @@ export default defineConfig({
                   ],
               },
           ],
-          }), sitemap()],
-
+          }),
+      sitemap()
+  ],
   vite: {
     plugins: [tailwindcss()],
     resolve: {

lychee.toml

@@ -38,12 +38,14 @@ require_https = true
 
 # Fallback extensions to apply when a URL does not specify one.
 # This is common in documentation tools that cross-reference files without extensions.
-fallback_extensions = ["md", "mdx", "html"]
+fallback_extensions = ["html"]
 
 #############################  Exclusions  ##########################
 
 # Exclude URLs and mail addresses from checking. The values are treated as regular expressions
-exclude = []
+exclude = [
+  "^file://.*#"
+]
 
 # Check fragments - internal links in pages
 include_fragments = true

package.json

@@ -14,8 +14,8 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "link-check-md": "lychee src/content/docs/**/*.md --root-dir $(pwd)/public",
-    "link-check-md-offline": "lychee src/content/docs/**/*.md --root-dir $(pwd)/public --offline",
+    "link-check-offline": "lychee --config ./lychee.toml --offline --root-dir \"$(pwd)/dist/\" --remap \"all-contributors.github.io $(pwd)/dist/\" 'dist/**/*.html'",
+    "link-check": "lychee --config ./lychee.toml --root-dir \"$(pwd)/dist/\" --remap \"all-contributors.github.io $(pwd)/dist/\" 'dist/**/*.html'",
     "lint": "markdownlint **/*.{md,mdx} --ignore node_modules",
     "lint-fix": "markdownlint **/*.{md,mdx} --ignore node_modules --fix"
   },
@@ -25,10 +25,12 @@
     "@astrojs/starlight-tailwind": "^4.0.1",
     "@tailwindcss/vite": "^4.1.13",
     "astro": "^5.6.1",
-    "sharp": "^0.34.2",
-    "autoprefixer": "^10.4.21", 
+    "autoprefixer": "^10.4.21",
     "postcss": "^8.5.6",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
     "sass-embedded": "^1.92.1",
+    "sharp": "^0.34.2",
     "tailwindcss": "^4.1.13"
   },
   "devDependencies": {

src/content/docs/bot/configuration.md

@@ -8,7 +8,7 @@ You can configure the all-contributors bot behaviour by updating the `.all-contr
 The data used to generate the contributors list will be stored there, and you
 can configure how you want `@all-contributors` to generate the list.
 
-> You are viewing the 🤖Bot Configuration, which is similar to the [CLI Configuration](../cli/configuration)
+> You are viewing the 🤖Bot Configuration, which is similar to the [CLI Configuration](/cli/configuration)
 
 These are the keys you can specify:
 
@@ -30,7 +30,7 @@ These are the keys you can specify:
 | `types`                          | Specify custom symbols or link templates for contribution types. Can override the documented types. | |
 | `linkToUsage`                    | Adds a footer with link to usage (either `true` or `false`)                                         | Default: `true` |
 | `skipCi`                         | Makes the CI ignore the commit. (either `true` or `false`)                                          | Default: `true` |
-| `contributors`                   | List of contributors for this project, this is updated by [@all-contributors add](usage#all-contributors-add) | |
+| `contributors`                   | List of contributors for this project, this is updated by [@all-contributors add](/bot/usage#all-contributors-add) | |
 
 ```json
 {
@@ -65,10 +65,10 @@ As you know, the default file for the contributors table is `README.md`. But if
 
 Here are the steps that may help you in achieving that. For the sake of this tutorial, the different file that we'll use is going to be named `CONTRIBUTORS.md`.
 
-1. Install the bot. See the [Installation](installation) page for instructions.
-2. Add your first contributor. See the [Bot Usage](usage) page for instructions.
+1. Install the bot. See the [Installation](/bot/installation) page for instructions.
+2. Add your first contributor. See the [Bot Usage](/bot/usage) page for instructions.
 3. Create the `CONTRIBUTORS.md` file.
-4. Copy the code which can be found in [this guide](installation#3-create-a-readmemd).
+4. Copy the code which can be found in [this guide](/bot/installation#3-create-a-readmemd).
 5. Modify the `files` key in the `.all-contributorsrc` JSON file to match your new file name.
 
    ```json

src/content/docs/bot/installation.mdx

@@ -24,7 +24,7 @@ import configureRepo from '@assets/configure-repositories.png';
 Ensure you have a `README.md` file at the root of the project (it can be empty).
 
 If you prefer your contributors table in a place other than the `README.md`; After merging your first bot PR, you can move your contributors table,
-see `files` in the [bot configuration](configuration)
+see `files` in the [bot configuration](/bot/configuration)
 
 Make sure to add this in the markdown:
 
@@ -65,4 +65,4 @@ Style, color, and other parameters can be customized to your liking — visit [s
 
 ## 4. Update your Contributing documentation
 
-Consider updating your `CONTRIBUTING.md` or similar with steps on how contributors can add themselves. You can even link to the [bot usage documentation](usage).
+Consider updating your `CONTRIBUTING.md` or similar with steps on how contributors can add themselves. You can even link to the [bot usage documentation](/bot/usage).

src/content/docs/bot/usage.mdx

@@ -7,7 +7,7 @@ import { Picture } from "astro:assets";
 import {Aside} from '@astrojs/starlight/components';
 import botUsage from '@assets/bot-usage.png';
 
-<Aside type="tip"> This usage documentation assumes you have already followed the [bot installation steps](installation).</Aside>
+<Aside type="tip"> This usage documentation assumes you have already followed the [bot installation steps](/bot/installation).</Aside>
 
 ## Bot Commands
 

src/content/docs/cli/configuration.md

@@ -4,4 +4,4 @@ title: CLI Configuration
 sidebar_label: Configuration
 ---
 
-Please refer to the  [bot documentation for CLI configuration information](../bot/configuration).
+Please refer to the  [bot documentation for CLI configuration information](/bot/configuration).

src/content/docs/cli/installation.mdx

@@ -23,7 +23,7 @@ npm i -D all-contributors-cli
 Alternatively, Arch Linux users can install the [`all-contributors-cli`](https://aur.archlinux.org/packages/all-contributors-cli) package from the AUR.
 
 <Aside type="tip">
-The CLI is node-based, if you don't wish to add a node dependency use the [@all-contributors bot 🤖](../bot/overview)
+The CLI is node-based, if you don't wish to add a node dependency use the [@all-contributors bot 🤖](/bot/overview)
 </Aside>
 
 ## 2. Init the Project
@@ -45,11 +45,11 @@ npx all-contributors add jfmengels doc
 npx all-contributors generate
 ```
 
-For more on the commands see [CLI usage](usage)
+For more on the commands see [CLI usage](/cli/usage)
 
 ## 4. Update your Contributing documentation
 
-Consider updating your `CONTRIBUTING.md` or similar with steps on how your contributors can add themselves. You can even link to the [cli usage documentation](usage).
+Consider updating your `CONTRIBUTING.md` or similar with steps on how your contributors can add themselves. You can even link to the [cli usage documentation](/cli/usage).
 
 ## 5. *Optionally* add shortcut scripts to your `package.json`
 

src/content/docs/cli/overview.md

@@ -17,4 +17,4 @@ You want to use the command line because:
 * You want to add contributors as part of your project scripts
 * You want to add contributors as part of your continuous integration (CI) process
 
-Similar to the bot, the CLI allows you to implement the [All Contributors](../specification) spec, without maintaining the contributor table by hand.
+Similar to the bot, the CLI allows you to implement the [All Contributors](/specification) spec, without maintaining the contributor table by hand.

src/content/docs/cli/usage.mdx

@@ -5,7 +5,7 @@ sidebar_label: Usage
 ---
 import { Aside } from '@astrojs/starlight/components';
 
-<Aside type="tip"> This usage documentation assumes you have already followed the [cli installation steps](installation). Below you will learn how to use the CLI with the `all-contributors` command, to keep things simple. If you are having any difficulties running the command on it's own, then give the `npx all-contributors-cli init` route a try 😺.</Aside>
+<Aside type="tip"> This usage documentation assumes you have already followed the [cli installation steps](/cli/installation). Below you will learn how to use the CLI with the `all-contributors` command, to keep things simple. If you are having any difficulties running the command on it's own, then give the `npx all-contributors-cli init` route a try 😺.</Aside>
 
 ## All-Contributors Command Line Interface Commands
 
@@ -38,7 +38,7 @@ all-contributors add jfmengels code,doc
 ```
 
 Where `username` is the user's GitHub or Gitlab username, and `contribution` is a
-`,`-separated list of contributions. See the [Emoji Key (Contribution Types Reference)](../../emoji-key)
+`,`-separated list of contributions. See the [Emoji Key (Contribution Types Reference)](/emoji-key)
 for a list of valid `contribution` types.
 
 <Aside type="tip"> **GitLab Users**: See the [additional requirements for GitLab users](#gitlab-users) </Aside>

src/content/docs/emoji-key.md

@@ -6,7 +6,7 @@ sidebar_label: Emoji Key ✨
 
 ## About the Emoji Table
 
-To have a contribution added when using the [Bot](bot/overview) or [CLI](cli/overview) use the keyword in the `Type` column.
+To have a contribution added when using the [Bot](/bot/overview) or [CLI](/cli/overview) use the keyword in the `Type` column.
 
 For example if you add a comment in an issue or Pull Request on GitHub like this:
 

src/content/docs/overview.mdx

@@ -27,5 +27,5 @@ Below is an example of how using the all-contributors spec table can recognize a
 </div>
 
 <Aside type="tip">
-You can use [the @all-contributors bot 🤖](bot/overview) to automate acknowledging contributors to your open source projects
+You can use [the @all-contributors bot 🤖](/bot/overview) to automate acknowledging contributors to your open source projects
 </Aside>

src/content/docs/project/contribute.mdx

@@ -77,7 +77,8 @@ All Contributors currently uses [Astro](https://docs.astro.build/) and the [Star
 
 To build the docs locally:
 
-1. Make sure `npm` is installed on your machine. Use the [nodejs documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) if you aren't sure how to install `npm`.
+Make sure `npm` is installed on your machine.
+Use the [nodejs documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) if you aren't sure how to install `npm`.
 
 To check that npm is installed run the following in your favorite shell:
 
@@ -92,7 +93,7 @@ If you don't have atleast version `.22` or higher, please install node or upgrad
 
 Install Astro, the Starlight Theme and all of the project dependencies using `npm i`.
 
-**`npm i` is shorthand for `npm install`**
+`npm i` is shorthand for `npm install`
 
 Once you have completed the above, you can launch a server locally that will build and run the docs locally. In your favorite shell run:
 
@@ -101,7 +102,7 @@ Once you have completed the above, you can launch a server locally that will bui
 * Then, go to `http://localhost:4321` and you will see the all contributors website there!
 * Refresh the browser page as needed when editing markdown pages.
 
-### Make changes - linting your contribution
+### Linting your contribution
 
 If you make changes to a markdown file in the site, then our linting action will
 check those changes. To run the linter yourself locally on the documentation before submitting a PR use:
@@ -112,6 +113,27 @@ You can also run it manually on specific files like this:
 
 `markdownlint --fix "src/content/docs/contribute.md"`
 
+### Checking links
+
+We use [Lychee](https://lychee.cli.rs/introduction/), a fast rust-based link checker, to check links in our documentation. We have created scripts that you can use to check links across the site after it is built to ensure that any changes that you have made have a valid link target.
+To install Lychee and run the link checker locally, follow the installation instructions in the [Lychee documentation](https://lychee.cli.rs/installation/). You can choose the installation approach that is best for you; the options include using a package manager like brew or scoop, installing from GitHub or building from source using Cargo.
+
+To check internal links, for example, links between different pages on the site or image references, run:
+
+```console
+npm run link-check-offline
+```
+
+This is the same test that is run in CI; it should pass before your contributions are merged.
+
+You can also check all links, including links to external resources like other websites:
+
+```console
+npm run link-check
+```
+
+<Aside type="caution">Checking links to online resources will often result in false positives, meaning that some links that work online might appear to be broken. Some sites may reject requests if they don't appear to be from a browser, or you may be rate-limited. It's good practice to check each link that Lychee flags as broken before you try to update it.</Aside>
+
 ## Add yourself as a contributor
 
 To add yourself to the table of contributors, follow the [bot usage instructions](../../bot/usage).

src/content/docs/project/implementations.md

@@ -5,7 +5,7 @@ sidebar_label: Who's using it?
 ---
 
 This is an alphabetical list of projects which have implemented the `all-contributors` specification. To add your project to this
-list, please [edit this page](contribute)!
+list, please [edit this page](/project/contribute)!
 
 - [all-contributors/all-contributors-cli](https://github.com/all-contributors/all-contributors-cli)
 - [all-contributors/all-contributors](https://github.com/all-contributors/all-contributors)