Docusaurus github actions

The modern approach to documentation has shifted from static, manually uploaded folders to a sophisticated "Docs-as-Code" philosophy. Central to this transition is Docusaurus, a powerful static site generator optimized for documentation, and GitHub Actions, a robust continuous integration and continuous delivery (CI/CD) platform. When these two technologies converge, the result is a seamless pipeline where a developer simply pushes Markdown files to a repository, and a fully optimized, globally accessible website is deployed automatically. This process eliminates the manual overhead of building the site locally and pushing artifacts to a hosting provider, ensuring that the live documentation always reflects the current state of the source code.

Implementing this workflow requires a precise orchestration of configuration files, environment variables, and workflow triggers. Whether using the modern GitHub Pages experience—which allows for deployment directly from an action without the need for a separate gh-pages branch—or integrating third-party CI/CD tools like Buddy or Azure Pipelines, the objective remains the same: absolute automation of the build-and-deploy cycle. This involves not only the deployment of the site but also the integration of quality assurance tools, such as Vale for prose linting, to ensure that the documentation meets professional linguistic standards before it ever reaches the end user.

Initializing the Docusaurus Environment

Before any automation can be configured, the Docusaurus project must be correctly initialized. This phase establishes the foundation of the site's structure and ensures that TypeScript is utilized for better type safety and developer experience.

To generate a new Docusaurus website, the following command is executed:

yarn create docusaurus <folder-name> classic --typescript

This command scaffolds a project using the "classic" template, which includes the necessary plugins for documentation and blogging, and configures it for TypeScript. The choice of TypeScript is critical as it allows for better maintainability of the configuration files and custom components, reducing runtime errors during the build process.

Mastering the docusaurus.config.js Configuration

The docusaurus.config.js file is the central nervous system of a Docusaurus project. For GitHub Pages deployment to function correctly, several specific constants and properties must be defined. Failure to align these values with the actual GitHub repository structure often leads to 404 errors or broken asset links (CSS/JS) upon deployment.

The configuration requires the definition of organization and project identifiers to dynamically construct URLs.

First, the constants for the organization and project must be declared:

const organizationName = "<github-organization-name>";
const projectName = "<repository-name>";

These variables are then utilized within the main configuration object to ensure the site is hosted at the correct location.

The URL and Base URL settings are critical for routing:

const config = { // (...) url: https://${organizationName}.github.io, };
const baseUrl = /${projectName}/;

The url property defines the root domain of the site, while the baseUrl defines the path under which the site is hosted. On GitHub Pages, if the project is not a User/Organization page (e.g., username.github.io), it is hosted at a project subpath. Setting the baseUrl to /${projectName}/ ensures that all internal links and asset paths are prefixed correctly, preventing the browser from looking for files at the root of the domain instead of the project folder.

Furthermore, the organizationName and projectName must be explicitly included in the config object:

const config = { // (...) organizationName, projectName, };

To enable "Edit this page" functionality, which allows users to contribute to the documentation by jumping directly to the GitHub editor, the editUrl must be configured within the presets. This requires a specific path pointing to the main branch of the repository.

The configuration for docs and blog edit URLs is as follows:

const config = { // (...) presets: [ [ "classic", /** @type {import('@docusaurus/preset-classic').Options} */ ({ // (...) docs: { // (...) editUrl: https://github.com/${organizationName}/${projectName}/tree/main/ }, blog: { // (...) editUrl: https://github.com/${organizationName}/${projectName}/tree/main/ }, }), ], ], };

By using these dynamic variables, the documentation becomes portable; if the project is renamed or moved to a different organization, only the constants at the top of the file need to be updated.

Deploying via the Modern GitHub Pages Experience

GitHub has evolved its Pages offering to move away from the legacy method of deploying from a specific branch (like gh-pages). The new experience allows GitHub Actions to deploy the build artifacts directly to the Pages hosting service.

To enable this, the following administrative steps must be taken in the GitHub interface:

• Navigate to the repository on GitHub.com.
• Go to the Settings tab.
• Select Pages from the left-hand sidebar.
• Under the Build and deployment section, locate the Source dropdown.
• Change the selection from Deploy from a branch to GitHub Actions.

Once this is enabled, the repository's environment settings will automatically reflect a new GitHub Environment named github-pages. This environment acts as a security and deployment boundary, allowing the GitHub Action to push the compiled static files to the Pages infrastructure without needing to commit those files back into the source repository. This keeps the Git history clean and prevents the "pollution" of the repository with build artifacts.

Implementing the GitHub Actions Workflow

The deployment strategy depends on whether the source code and the deployment target reside in the same repository or across different repositories.

Single Repository Deployment

When the source and deployment repos are the same, the workflow is streamlined. A job—often named deploy—is triggered when a push is made to the main branch or when a pull request is merged. This ensures that only reviewed and approved code reaches the live site.

If the Docusaurus project is not located at the root of the repository (e.g., it is in a /docs folder), the workflow must be configured with a default working directory. This is achieved by adding a defaults section to the YAML file:

defaults: run: working-directory: /your-folder-path

Cross-Repository Deployment (Remote)

Deploying to a remote repository is more complex because it requires authentication across different security contexts. In this scenario, the source repository triggers a build, and the resulting artifacts are pushed to a gh-pages branch in a separate repository.

Because this involves pushing to a different repository, SSH authentication is required. This process involves:

• Generating a new SSH key pair.
• Adding the public key to the target repository's deploy keys.
• Storing the private key as a GitHub Secret in the source repository.

Alternative CI/CD Pipelines

While GitHub Actions is the native choice, other platforms can be used to orchestrate Docusaurus deployments.

Buddy CI/CD Integration

Buddy provides a visual pipeline builder that can automate the yarn deploy command. The setup process is as follows:

• Create a new project in Buddy and connect it to the GitHub repository.
• Navigate to the Pipelines view and create a new pipeline.
• Set the trigger mode to On push and select the target branch.
• Add a Node.js action.
• Execute the following commands in the action's terminal:

GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
git config --global user.email "<YOUR_GH_EMAIL>"
git config --global user.name "<YOUR_GH_USERNAME>"
yarn deploy

This sequence configures the git identity within the runner and utilizes the Docusaurus built-in deploy script to push the site to GitHub Pages.

Azure Pipelines Configuration

Azure Pipelines offers a more enterprise-oriented approach to deployment. The process involves creating an organization and connecting the GitHub repository. A critical step is the management of secrets.

A Personal Access Token (PAT) must be generated from GitHub with the repo scope. This token is then stored in the Azure pipeline as an environment variable named GH_TOKEN. Additional variables such as GH_EMAIL and GH_NAME must also be configured and marked as secret to prevent them from appearing in the build logs.

Quality Assurance with Vale Linting

A professional documentation pipeline does not just deploy code; it ensures the quality of the prose. Integrating a linter like Vale into the GitHub Actions workflow allows for the automated checking of style, grammar, and terminology.

To implement this, a new workflow file named vale-linter.yml must be created in the .github/workflows directory.

The configuration for the Vale Lint Checker is as follows:

```yaml
name: Vale Lint Checker
on:
push:
branches:
- main
pullrequest:
branches:
- '*'
workflowdispatch:

jobs:
prose:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: 16
- name: Vale Lint
uses: errata-ai/vale-action@reviewdog
with:
files: .
env:
GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
```

This workflow is triggered on every push to main, every pull request, or via a manual trigger. It ensures that any prose violations are flagged during the PR process, preventing low-quality content from being merged. After creating this file, the changes must be committed and pushed:

git add .
git commit -m "changes"
git push

Comparison of Deployment Methods

The following table provides a technical comparison between the different deployment paths available for Docusaurus.

Technical Troubleshooting and Common Pitfalls

Many users encounter issues when jumping directly to deployment instructions without completing the prerequisite configuration. A common failure point is the "404 Not Found" error after a successful build. This is almost always caused by a mismatch between the baseUrl in docusaurus.config.js and the actual URL where GitHub Pages is hosting the site.

For instance, if the site is at https://org.github.io/repo/, but the baseUrl is set to /, the browser will attempt to load assets from the root domain (https://org.github.io/), resulting in failed requests. The baseUrl must strictly match the repository name: /${projectName}/.

Another frequent issue is the "Skipped" status of deployment jobs during pull requests. When both a test job and a deploy job are in the same workflow, the deploy job is often skipped during PRs to prevent unfinished code from going live. To solve this, it is recommended to split these into separate workflow files, ensuring that the PR check suite accurately reflects the status of the code without being clouded by a skipped deployment step.

Conclusion: The Impact of Automated Documentation

The integration of Docusaurus with GitHub Actions transforms documentation from a static chore into a dynamic software development lifecycle (SDLC) process. By utilizing the "Modern GitHub Pages" experience, developers can decouple their source code from the build artifacts, maintaining a clean repository while benefiting from instant, automated deployments.

The ability to integrate prose linting via Vale and complex CI/CD pipelines via Azure or Buddy ensures that the documentation is not only technically accurate but also linguistically consistent. The shift toward this infrastructure allows teams to treat documentation as a first-class citizen of the codebase, applying the same rigor to the "help" files as they do to the application code. Ultimately, this level of automation reduces the time-to-publish and ensures that the end-user always has access to the most current and polished version of the project's documentation.

Sources

1. GitHub Pages Docusaurus Example
2. Docusaurus Deployment Guide
3. Docusaurus Discussion 10453
4. freeCodeCamp: Docs as Code with Docusaurus