docs: add docs on using Lychee and fix lychee's build (#939)

JimMadge · flpm · lwasser · web-flow · commit afc3c22aa866 · 2025-10-07T19:02:44.000-06:00
* docs: remove Docusaurus website and docs * docs: remove netlify.toml * docs: add astro config * docs: add astro / starlight docs source * docs: add public all-contrib static files * docs: dependencies, update package.json * docs: added favicons and related images * docs update node version in .nvmrc; remove .astro; fix .gitignore * docs: small updates to github CI * docs: update .gitignore with more astro related files * docs: small updates to clarify config * chore(link checker): Move to Lychee for link checking (#889) * chore(package.json): add angular commit helper deps and script * test(link checking): add lychee configuration re #852 * test(link check): add script to check links in Markdown source * fix: correct link to eslint commit convention * fix: correct bot usage image path * test: add mdx to fallback extentions * fix: remove broken link * test: check links internal to a page * test: add root dir to link checking This ensures links to an absolute path (starting with '/') are directed to the public directory. fix 852 * ci: add markdownlint dep and script * style: fix linting errors * ci: install deps for lint workflow * ci: add offline link check for PRs and push to main This workflow will only check links to local files and not make network requests. There should therefore be no false negatives and it is safer to use as a required CI item. * docs(readme): sync readme file in docs upgrade branch with main (#895) * chore(branch rename): rename master --> main throughout so ci runs and docs are correct (#890) chore(rename master to main branch): we renamed the master branch; this updates all actions & docs * docs: add JimMadge as a contributor for review (#892) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> Co-authored-by: Leah Wasser <leah@pyopensci.org> * docs: add JHWelch as a contributor for doc (#894) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add landing page to astro documentation (#887) docs: make index dynamic and add images docs: lint all docs and add markdown lint dep docs: lint Correct image path * docs:remove placeholder index page (#899) docs:remove placeholder index page * docs: style landing page, add branded fonts and colors & tailwind (#901) * docs(style): source gfonts poppins * docs(style): add custom style/ setup tailwind * docs(img): add and update images * docs(img): add and update images * docs(config): cleanup landing and config * chore(deps): update to support tailwind * chore(css): setup tailwind css * docs: add graphics for home page and style buttons * docs: add buttons * docs: missed a few more image updates * chore(deps): correct dependency location in package.lock * chore(clean): clean old files * chore: add poppins font license --------- Co-authored-by: Jim Madge <jim@jmadge.com> * docs: add documentation for mdx pages and update images for the overview section (#915) * docs: update images and document how to add content to our docs docs: update images and edit text for all intro pages docs: clean up all pages in the general overview section docs: add description for Ideas, projectManagement and promotion (#829) docs: ✏️ Add dark mode README logo (#741) Co-authored-by: Leah Wasser <leah@pyopensci.org> Co-authored-by: Jim Madge <jim@jmadge.com> * enh(image): bring in dark mode compatible logo * docs: tidy adding images section Move path alias section up and adjust Apply suggestions from code review Co-authored-by: Jim Madge <jim+github@jmadge.com> * style: linting fixes for emoji table and other content --------- Co-authored-by: Jim Madge <jim@jmadge.com> Co-authored-by: Jim Madge <jim+github@jmadge.com> * chore(ci for docs): Get docs online via github pages (#914) * docs: get docs online via github pages new branch * chore: set site and base according to astro docs Astro docs: https://docs.astro.build/en/guides/deploy/github/#how-to-deploy suggest how to specifiy the site url and base for GitHub pages. --------- Co-authored-by: Jim Madge <jim@jmadge.com> * docs(fix basurl): update baseurl to support github pages (#924) * chore(ci): Fix offline link check (#923) * ci: correct workflow file format 🤦 * ci: add root directory to offline link check This ensures that the link checkers knows where to look for absolute links. * docs: update images and breakout links for the "bot" section of the documentation (#919) * docs: update images and document how to add content to our docs docs: update images and edit text for all intro pages docs: clean up all pages in the general overview section docs: add description for Ideas, projectManagement and promotion (#829) docs: ✏️ Add dark mode README logo (#741) Co-authored-by: Leah Wasser <leah@pyopensci.org> Co-authored-by: Jim Madge <jim@jmadge.com> * enh(image): bring in dark mode compatible logo * docs: tidy adding images section Move path alias section up and adjust Apply suggestions from code review Co-authored-by: Jim Madge <jim+github@jmadge.com> * style: linting fixes for emoji table and other content * docs: fix links and breakouts in bot section * Apply suggestions from code review Co-authored-by: Jim Madge <jim+github@jmadge.com> --------- Co-authored-by: Jim Madge <jim@jmadge.com> Co-authored-by: Jim Madge <jim+github@jmadge.com> * docs: add Netlify badge to home page (#927) docs: add netlify badge for open source plan * docs: import styles globally rather than inline in a file (#933) docs(styles): apply stylesheets globally docs: document custom styles * Docs: Fix images and links in the last sections of the docs (#931) docs: fix links and images on last sections * chore: add merge commit to handle merge conflicts when we merge into main (#929) * chore(ci): add dependabot config for actions (#865) * chore(ci): bump actions/checkout from 3 to 5 (#883) Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 5. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v3...v5) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: '5' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(ci): bump actions/setup-node from 3 to 4 (#882) Bumps [actions/setup-node](https://github.com/actions/setup-node) from 3 to 4. - [Release notes](https://github.com/actions/setup-node/releases) - [Commits](actions/setup-node@v3...v4) --- updated-dependencies: - dependency-name: actions/setup-node dependency-version: '4' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(ci): bump actions/upload-pages-artifact from 3 to 4 (#881) * chore(ci): bump actions/upload-pages-artifact from 3 to 4 Bumps [actions/upload-pages-artifact](https://github.com/actions/upload-pages-artifact) from 3 to 4. - [Release notes](https://github.com/actions/upload-pages-artifact/releases) - [Commits](actions/upload-pages-artifact@v3...v4) --- updated-dependencies: - dependency-name: actions/upload-pages-artifact dependency-version: '4' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> * Update .github/workflows/build-website.yml * chore(ci): update actions --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Leah Wasser <leah@pyopensci.org> * chore(branch rename): rename master --> main throughout so ci runs and docs are correct (#890) chore(rename master to main branch): we renamed the master branch; this updates all actions & docs * docs: ✏️ fix links to doc site and small bug in footer.js (#871) * docs: ✏️ fix links to doc site and small bug in footer.js This change fixes an error in the footer and also updates some broken links. ✅ Closes: 870 * Update website/static/index.html Co-authored-by: Leah Wasser <leah@pyopensci.org> * Update docs/overview.md --------- Co-authored-by: Jim Madge <jim+github@jmadge.com> * docs: add JimMadge as a contributor for review (#892) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> Co-authored-by: Leah Wasser <leah@pyopensci.org> * docs: add JHWelch as a contributor for doc (#894) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add lwasser as a contributor for review (#897) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add JimMadge as a contributor for infra (#896) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> Co-authored-by: Jim Madge <jim@jmadge.com> * docs: ✏️ Add dark mode README logo (#741) Co-authored-by: Leah Wasser <leah@pyopensci.org> Co-authored-by: Jim Madge <jim@jmadge.com> * docs: add RichLewis007 as a contributor for bug, and doc (#906) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add parthamk as a contributor for doc (#909) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add rebeccaringuette as a contributor for ideas (#910) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * Change build branch from 'master' to 'docs-upgrade' * docs: add description for Ideas, projectManagement and promotion (#829) * docs: add KhushiPandey8 as a contributor for doc (#918) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add lwasser as a contributor for doc (#921) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: add JimMadge as a contributor for doc (#922) * docs: update README.md [skip ci] * docs: update .all-contributorsrc [skip ci] --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> * docs: linting fix * docs: remove last docusaurus files * docs: update * chore: fix linting step to handle mdx * chore: lint * fix: links --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jim Madge <jim+github@jmadge.com> Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> Co-authored-by: Jim Madge <jim@jmadge.com> Co-authored-by: Jordan Welch <JordanHWelch@gmail.com> Co-authored-by: Reshama Shaikh <reshama.stat@gmail.com> * docs: remove bold around code block * docs: remove some formatting * test: add mdx files to link check scripts * docs: add docs for using Lychee * test: exclude astro aliases from link check * ci: check mdx files for links * WIP: fix links in mdx files * Revert "WIP: fix links in mdx files" This reverts commit 92aa7b5. * test: run link check on HTML * Update links * docs: add automatic links to headings * test: correct link check scripts * docs: fix links to fragments * docs: correct and exclude links to fragments The server redirects these correctly, however they don't match file paths so the link checker fails * docs: update link check docs * ci: build site before link check * ci: remove remap from workflow command This seems to create a recursion * Update src/content/docs/project/contribute.mdx Co-authored-by: Leah Wasser <leah@pyopensci.org> * Update src/content/docs/project/contribute.mdx Co-authored-by: Leah Wasser <leah@pyopensci.org> * Update src/content/docs/project/contribute.mdx Co-authored-by: Leah Wasser <leah@pyopensci.org> * Update src/content/docs/project/contribute.mdx Co-authored-by: Leah Wasser <leah@pyopensci.org> * Update src/content/docs/project/contribute.mdx Co-authored-by: Leah Wasser <leah@pyopensci.org> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Felipe Moreno <felipe@flpm.dev> Co-authored-by: Leah Wasser <leah@pyopensci.org> Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jordan Welch <JordanHWelch@gmail.com> Co-authored-by: Reshama Shaikh <reshama.stat@gmail.com>
diff --git a/.github/workflows/offline-link-check.yml b/.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
diff --git a/.gitignore b/.gitignore
@@ -35,7 +35,6 @@ dist
 # Astro generated types
 .astro/
 
-
 .lycheecache
 dist/
 
diff --git a/astro.config.mjs b/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: {
diff --git a/lychee.toml b/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
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/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": {
diff --git a/src/content/docs/bot/configuration.md b/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
diff --git a/src/content/docs/bot/installation.mdx b/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).
diff --git a/src/content/docs/bot/usage.mdx b/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
 
diff --git a/src/content/docs/cli/configuration.md b/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).
diff --git a/src/content/docs/cli/installation.mdx b/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`
 
diff --git a/src/content/docs/cli/overview.md b/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.
diff --git a/src/content/docs/cli/usage.mdx b/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>
diff --git a/src/content/docs/emoji-key.md b/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:
 
diff --git a/src/content/docs/overview.mdx b/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>
diff --git a/src/content/docs/project/contribute.mdx b/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).
diff --git a/src/content/docs/project/implementations.md b/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)
diff --git a/src/content/docs/specification.mdx b/src/content/docs/specification.mdx
diff --git a/src/content/docs/tooling.mdx b/src/content/docs/tooling.mdx
diff --git a/src/content/docs/usage-tips.mdx b/src/content/docs/usage-tips.mdx
diff --git a/website/core/Footer.js b/website/core/Footer.js
diff --git a/website/siteConfig.js b/website/siteConfig.js
