Setting up a GitHub Docusaurus repo and deploying it using GitHub Action and Pages

[AaronNGray]

Hi,

I am looking for an example of how to deploy a Docusaurus documentation website with the same VERSION and LANGUAGE dropdowns, are these plugins ? I need to have my versioning parallel to my GitHub version tags.

I have looked at https://docusaurus.io/docs/deployment#deploying-to-github-pages

Also to deploy it so it looks simular in format and location to Docusaurus own Docs on a GitHub Pages sub page.

I cloned Docusaurus, modifying the default export at docusaurus.config.ts as https://github.com/AaronNGray/docusaurus-docs-test

I set up GitHub Actions and am now getting the following error :-

Rendering Markup: assets/css/style.scss github-pages 232 | Error: No such file or directory @ dir_chdir0 - /github/workspace/docs

Annotations
1 error and 1 warning
build Logging at level: debug GitHub Pages: github-pages v232 GitHub Pages: jekyll v3.10.0 Theme: jekyll-theme-primer Theme source: /usr/local/bundle/gems/jekyll-theme-primer-0.6.0 Requiring: jekyll-github-metadata Requiring: jekyll-seo-tag Requiring: jekyll-coffeescript Requiring: jekyll-commonmark-ghpages Requiring: jekyll-gist Requiring: jekyll-github-metadata Requiring: jekyll-paginate Requiring: jekyll-relative-links Requiring: jekyll-optional-front-matter Requiring: jekyll-readme-index Requiring: jekyll-default-layout Requiring: jekyll-titles-from-headings GitHub Metadata: Initializing... Source: /github/workspace/./docs Destination: /github/workspace/./docs/_site Incremental build: disabled. Enable with --incremental Generating... Generating: JekyllOptionalFrontMatter::Generator finished in 1.1832e-05 seconds. Generating: JekyllReadmeIndex::Generator finished in 6.031e-06 seconds. Generating: Jekyll::Paginate::Pagination finished in 3.236e-06 seconds. Generating: JekyllRelativeLinks::Generator finished in 2.2171e-05 seconds. Generating: JekyllDefaultLayout::Generator finished in 1.1e-05 seconds. Generating: JekyllTitlesFromHeadings::Generator finished in 6.622e-06 seconds. Rendering: assets/css/style.scss Pre-Render Hooks: assets/css/style.scss Rendering Markup: assets/css/style.scss github-pages 232 \| Error: No such file or directory @ dir_chdir0 - /github/workspace/docs

Hoping this is a simple error.

Many thanks in advance !

[harshagarwalnyu]

The error is from Jekyll, not Docusaurus. GitHub Pages defaults to Jekyll-based builds unless you explicitly disable it. Your workflow is triggering GitHub Pages' legacy Jekyll pipeline, which is trying to process your Docusaurus output directory as a Jekyll site.

The fix: add a .nojekyll file

In your Docusaurus config, add trailingSlash: false and ensure .nojekyll is created during the build:

// docusaurus.config.ts
export default {
  // ...
  trailingSlash: false,
};

In your GitHub Actions workflow, add a step after the build:

- name: Build
  run: npm run build

- name: Add .nojekyll
  run: touch build/.nojekyll

- name: Deploy to GitHub Pages
  uses: actions/upload-pages-artifact@v3
  with:
    path: build/

The correct GitHub Actions workflow for Docusaurus + GitHub Pages:

name: Deploy Docusaurus to Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: touch build/.nojekyll
      - uses: actions/upload-pages-artifact@v3
        with:
          path: build/

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

In GitHub repo Settings → Pages → set Source to "GitHub Actions" (not "Deploy from branch"). That's the setting that switches from Jekyll to the artifact-based pipeline.

For versioning: Docusaurus's built-in versioning (docusaurus docs:version X.Y.Z) creates snapshot copies under versioned_docs/. This doesn't automatically sync with GitHub tags, but you can wire a workflow step: run: npm run docusaurus docs:version ${{ github.ref_name }} on release tag pushes.

[slorber]

Hi,

I am looking for an example of how to deploy a Docusaurus documentation website with the same VERSION and LANGUAGE dropdowns, are these plugins ?

The things appearing in the navbar are navbar items you can add to your site configuration. It's documented in our official docs and our built-in tutorial embedded in newly initialized sites:

https://tutorial.docusaurus.io/docs/tutorial-extras/manage-docs-versions

I need to have my versioning parallel to my GitHub version tags.

Docusaurus may not work like other docs systems you are used to. Docusaurus assumes you are putting all your doc versions on the main branch, and it assembles a single SPA site aggregating all versions.

If this is not what you look for and want to keep versioned docs on versioned branches, you need to build one independant Docusaurus site per versioned branch, instead of one consolidated site. GitHub pages is not a good host for that because it doesn't support multiple deployments at once afaik.

[harshagarwalnyu]

Hi Aaron,

I forked your repository, fixed the configuration and build dependencies, and submitted a Pull Request: AaronNGray#1.

Here is what was fixed:

1. URL Sub-path Error: In website/docusaurus.config.ts, url had a sub-path https://AaronNGray.github.io/docusaurus-docs-test. Docusaurus forbids sub-paths in url. I corrected it to https://AaronNGray.github.io and passed the subpath through the baseUrl instead.

2. Monorepo Build Requirement: Since you cloned the entire Docusaurus monorepo, dependencies (like @docusaurus/core) must be compiled before the website can be built. Root yarn install automatically triggers the postinstall script compilation.

3. GitHub Actions Workflow: Added a modern .github/workflows/deploy.yml that correctly runs and builds the site using Yarn and deploys the artifact to GitHub Pages.

Once you merge the PR, go to Settings -> Pages in your repository and set the Source under Build and deployment to "GitHub Actions".