Automate documentation publishing to GitHub Pages

[lucaaamaral]

Context

The documentation source is written in markdown. Docusaurus does not serve markdown directly — it must be compiled at build time into static HTML/CSS/JS via docusaurus build (i.e. npm run build), which produces a build/ directory containing the complete, ready-to-serve static site. This is a one-time compilation step; no server-side processing is needed at runtime to render the pages.

The actual build logic lives in package.json ("build": "docusaurus build"). Both the Dockerfile and a direct Node.js setup are just callers of this same script — neither embeds its own build logic.

The project already has this wired up in docusaurus/Dockerfile:

• The prod stage runs npm run build and produces the build/ directory.
• The serve and caddy stages consume that output to serve the site, but these are oriented towards self-hosted deployment (Caddy in particular adds automatic SSL/TLS via Let's Encrypt).

On the CI side, the Docs Check workflow (docs-test.yml) runs on every pull request and push to main. Its docusaurus-test job uses Docker specifically because it needs to validate runtime behavior: it builds the dev target, starts the dev server container, and health-checks it with curl on port 3000. This is a different concern from producing static artifacts — it verifies the site actually starts and responds. The workflow also runs markdown linting, translation consistency, frontmatter/filename sync, broken symlinks, and external link checks. There is also a docs-fix.yml workflow that triggers on check failures to produce auto-fix patches.

The Docusaurus config already declares organizationName and projectName for GitHub Pages, and a .nojekyll file is present in static/.

Problem

After a pull request is merged and all checks pass, the updated documentation is not made available to readers. There is no deployment pipeline — nothing takes the build output and publishes it. The existing Docker targets and CI workflows validate and build the site, but the last mile of actually deploying it to GitHub Pages is missing.

Solution

Add a GitHub Actions workflow that automatically builds and publishes the Docusaurus site to GitHub Pages using the deploy to GitHub Pages action when changes are merged to main.

Key considerations for whoever implements this:

• The Docs Check workflow (docs-test.yml) already validates the Docusaurus build on both pull requests and pushes to main. The deployment workflow should avoid duplicating that build logic to keep maintenance overhead low.
• The Docusaurus project is already configured for GitHub Pages (organizationName, projectName in docusaurus.config.js, .nojekyll in static/).
• The existing docusaurus/Dockerfile has a prod build stage that produces the static site output, which may be relevant context.

Non-goals

• External hosting platforms — GitHub Pages is the only target.
• Changes to the existing PR validation workflow.

[basakankit]

Hi @DarshanCode2005, I have already been assigned the task by @lucaaamaral previously on slack.
I will keep my progress updated.
Thanks!

[basakankit]

Hi @lucaaamaral, I have submitted for PR. If I need to rectify anything let me know.
For reference the pr: Added GitHub Actions workflow for documentation deployment.#52

[lucaaamaral]

@basakankit I have not forgotten you, I'll test your changes next week and if all goes well, merge it. Thank you for your patience.