Validate Docs Generation

Make sure everything is working as expected before deployment

GitHub Pages

You can easily verify your documentation generation with the following steps:

Create a new file in the .github/workflows directory named validate-docs-generation.yml. But you can also add it to your existing CI workflow.
Add the content below to the file.
Push to main to enable the workflow.

From now, each time you create a PR against the main branch, the workflow will be triggered. This ensures that your deployment will never fail in the future and your code and markdown is correctly formatted.

Workflow file

.github/workflows/validate-docs-generation.yml

name: Validate Docs Generation

on:
  pull_request:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  generate-docs:
    name: Generate Docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - run: npm i -g pnpm @antfu/ni

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
          cache-dependency-path: .docs/pnpm-lock.yaml

      - name: Install dependencies
        run: cd .docs && nci

      - name: Use NODE_ENV=production
        run: echo "NODE_ENV=production" >> $GITHUB_ENV

      - name: Static HTML export with Nuxt
        run: cd .docs && nr generate

  lint-markdown:
    name: Lint Markdown
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - run: npm i -g pnpm @antfu/ni

      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
          cache-dependency-path: .docs/pnpm-lock.yaml

      - run: cd .docs && nci

      - run: cd .docs && nr lint:md

  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - run: npm i -g pnpm @antfu/ni

      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
          cache-dependency-path: .docs/pnpm-lock.yaml

      - run: cd .docs && nci

      - run: cd .docs && nr lint

Update .docs with the path to your documentation directory.

Lint and format

In order to unified the code and markdown formatting, you can use the following commands, we use eslint, markdownlint and case-police.

First, you need to install the following dependencies:

pnpm add -D eslint @nuxt/eslint-config markdownlint-cli case-police

Configuration files

You need to add these files in your docs folder.

.eslintrc.cjs

module.exports = {
  root: true,
  extends: '@nuxt/eslint-config',
  rules: {
    'vue/max-attributes-per-line': 'off',
    'vue/multi-word-component-names': 'off'
  }
}

.eslintignore

dist
node_modules
.output
.nuxt

.markdownlint.yml

# Default state for all rules
default: true
# Disable max line length
MD013: false
# Disable space after hash on atx style heading
MD018: false
# Allow duplicated heading for different sections
MD024:
  allow_different_nesting: true
  siblings_only: true
# Allow multiple top-level headings
MD025: false
# Allow inline HTML
MD033: false
# Allow non blank lines around list
MD032: false
MD046:
  style: fenced

.markdownlintignore

**/node_modules

content/0.index.md

Commands

You must also add script to package.json

{
  "scripts": {
    "lint": "eslint --cache .",
    "lint:fix": "eslint --cache --fix .",
    "lint:md": "markdownlint . && case-police ./**/*.md",
    "lint:md:fix": "markdownlint . --fix && case-police --fix ./**/*.md"
  }
}

You must add .eslintcache to your .gitignore file.

And voilà! You can now lint and format your code and markdown with the following commands:

# Lint
pnpm run lint
# Lint and fix
pnpm run lint:fix
# Lint markdown
pnpm run lint:md
# Lint and fix markdown
pnpm run lint:md:fix

Edit this page on GitHub

GuideCustomization

GuideDeployment