https://github.com/starrocks/docusaurus-build

https://github.com/starrocks/docusaurus-build

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/starrocks/docusaurus-build
• Owner: StarRocks
• Created: 2023-10-27T21:13:00.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2023-11-22T22:53:01.000Z (about 1 year ago)
• Last Synced: 2023-11-22T23:33:25.271Z (about 1 year ago)
• Language: JavaScript
• Size: 521 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# docusaurus-build

This is a test-harness for Docusaurus v3. It is meant to be pulled by a GitHub

workflow and used to test Markdown files.

## Example workflow

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

```