Deployment

Show your beautiful documentation to the world!

GitHub Pages

You can easily deploy your documentation to GitHub Pages with the following steps:

Create a new file in the .github/workflows directory named deploy-docs.yml.
Add the content below to the file.
Go to the repository settings and enable GitHub Pages by Actions.
Add the following secrets to your repository in the actions environment:
- NUXT_APP_BASE_URL: <your base URL>
- NUXT_PUBLIC_SITE_URL: <your site URL>
Push to main to trigger the workflow.

The base URL is the path where the navigation start. For example: /armonik-docs-theme/ or /.

The site URL is the URL of your site. For example: https://aneoconsulting.github.io/armonik-docs-theme/.

Workflow file

.github/workflows/deploy-docs.yml

name: Deploy Docs to Pages

env:
  NUXT_APP_BASE_URL: ${{secrets.NUXT_APP_BASE_URL}}
  NUXT_PUBLIC_SITE_URL: ${{secrets.NUXT_PUBLIC_SITE_URL}}

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  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: Static HTML export with Nuxt
        run: cd .docs && nr generate
        env:
          NITRO_PRESET: github-pages

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: .docs/.output/public

  deploy:
    needs: generate-docs
    name: Deploy to GitHub Pages
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Update .docs with the path to your documentation directory.

Don't forget to enable GitHub Pages by Actions in the repository settings.

Favicon

If you provide a base URL different from /, you need to update the favicon path in the nuxt.config.ts file.

nuxt.config.ts

export default defineNuxtConfig({
  // ...
  app: {
    head: {
      link: [
        {
          rel: 'icon',
          type: 'image/ico',
          href: `${process.env.NUXT_APP_BASE_URL ?? '/'}favicon.ico`,
        }
      ]
    }
  },
})

Runtime config

You also need to update some runtime config key to make sure the links are working correctly.

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      siteName: '<your site name>',
      siteDescription: '<your site description>',
    }
  },
})

Edit this page on GitHub

GuideValidate Docs Generation

GuideUpdate