Skip to main content

Deploying Docs

This site is deployed to GitHub Pages at docs.teamjod.app.

How It Works​

The site is built with Docusaurus and deployed via a GitHub Actions workflow that:

  1. Checks out the selected branch
  2. Runs npm ci and npm run build to produce static HTML/CSS/JS in the build/ directory
  3. Uploads the build output as a GitHub Pages artifact
  4. Deploys the artifact to GitHub Pages
What is an artifact?

An artifact is a packaged bundle of files produced by a GitHub Actions workflow. In our case, the build/ directory (containing all the generated HTML, CSS, and JS) is compressed and uploaded as an artifact. The deploy step then downloads this artifact and publishes it to GitHub Pages. You can view and download past artifacts from the workflow run summary page.

The workflow file lives at .github/workflows/deploy-production.yml.

Custom Domain​

The custom domain docs.teamjod.app is configured via:

  • static/CNAME — tells GitHub Pages which domain to serve
  • A DNS CNAME record pointing docs.teamjod.app to jod-app.github.io
  • HTTPS is enforced automatically by GitHub (via Let's Encrypt)

How to Deploy​

Automatic (push to main)​

Every push to main automatically triggers a deploy. Just merge your PR and the site updates within ~1-2 minutes.

Manual (any branch)​

  1. Go to the Actions tab in the docs repo
  2. Click "Deploy Prod (docs.teamjod.app)" in the left sidebar
  3. Click "Run workflow"
  4. Select the branch you want to deploy (defaults to main)
  5. Click the green "Run workflow" button

The build takes ~1-2 minutes. Once the workflow completes, the site is live.

Local Development​

# Install dependencies
npm install

# Start dev server on port 4000
npm start

# Build the site (same as what CI runs)
npm run build

# Preview the built site locally
npm run serve

Troubleshooting​

Docusaurus validates all internal links during build. If you see "broken links" errors, check that:

  • Markdown links point to existing files using the correct relative path
  • Links to sibling directories use ../directory-name/ (not ./filename.md)
  • Any renamed or moved pages have their incoming links updated

Changes not showing up after deploy​

  • GitHub Pages can take 1-2 minutes to propagate after the workflow completes
  • Hard-refresh your browser (Cmd+Shift+R) to bypass cached assets