This is a test-harness for Docusaurus v3. It is meant to be pulled by a GitHub workflow and used to test Markdown files.
This workflow goes into the repo that contains your Markdown files. It pulls the slimmed down Docusaurus v3 files from this repo, and then it pulls the repo that contains your Markdown files.
When it pulls the Markdown files it checks them out into a directory named docs. If your Markdown files are already in a dir named docs/, then adjust the path: line of the workflow.
The docusaurus_config.js file has both broken link settings set to throw as we don't tolerate broken links. There is one sample Markdown file in our doc repos (README.md) that contains example markdown links that are invalid. I was surprised that these caused failures since they are in backticks, but they do. There is a run rm README.md in the workflow to avoid this issue.
Unfortunately the link checking of Docusaurus does not catch links missing the .md extension. Lychee to the rescue in the workflow below.
name: testbuild document site
on: [push]
jobs:
PR_check:
runs-on: ubuntu-latest
steps:
# This first checkout gets the test setup
# which is basically a default Docusaurus
# build with the broken links checks set
# to throw an exception.
- uses: actions/checkout@v4
with:
repository: 'StarRocks/docusaurus-build'
# this second checkout gets the docs from this
# repo and checks them out to a dir named:
# `docs`
- uses: actions/checkout@v4
with:
path: 'docs'
# The README file has some sample markdown that fails
# link checking
- run: rm ./docs/README.md
- uses: actions/setup-node@v3
with:
node-version: 18
- name: docusaurus-mdx-checker
if: always()
run: |
npx docusaurus-mdx-checker -c docs
- name: link check
if: always()
uses: lycheeverse/[email protected]
with:
fail: true
args: >
--config docs/lychee.toml
--offline "docs/**/*.md"
- run: yarn install --frozen-lockfile
- run: yarn build