Skip to main content

Feature: Configurable Repository URLs

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

Status: Completed ✅​

Goal: Make the documentation site work on any fork without manual URL changes.

Completed: 2026-01-16

PR: #16

Source: INVESTIGATE-docusaurus-enhancements.md

Prerequisites: None (this is the foundation) Blocks: All other website enhancement plans depend on this Priority: Critical

CI/CD Note: All phases can be validated locally with npm run build. Push and merge to main once after Phase 4 to run the full CI/CD pipeline. The pipeline takes 15+ minutes, so avoid multiple pushes.

Problem​

The site currently has hardcoded URLs pointing to terchris/devcontainer-toolbox. This causes issues:

  1. Contributors forking the repo get broken links
  2. GitHub Pages deploys to wrong URL on forks
  3. "Edit this page" links point to wrong repository
  4. Manual changes required for each fork

Files with hardcoded URLs:

  • website/docusaurus.config.ts - url, baseUrl, organizationName, editUrl, navbar/footer links
  • README.md - documentation site links
  • Various .md files - GitHub links

Solution​

Use environment variables with sensible defaults. GitHub Actions automatically passes repository context, and local development uses the defaults.

Phase 1: Update Docusaurus Config — ✅ DONE​

Tasks​

  • 1.1 Add environment variable reading at top of docusaurus.config.ts ✓
  • 1.2 Replace hardcoded values in config (url, baseUrl, organizationName, projectName) ✓
  • 1.3 Update editUrl to use variables ✓
  • 1.4 Update navbar GitHub link ✓
  • 1.5 Update footer links to use variables ✓

Validation​

Run npm run build in website folder - should complete without errors.

User confirms config changes look correct.

Phase 2: Update GitHub Actions — ✅ DONE​

Tasks​

  • 2.1 Update .github/workflows/deploy-docs.yml to pass environment variables ✓
  • 2.2 Verify the workflow file syntax is valid ✓

Validation​

Workflow updated with GITHUB_ORG and GITHUB_REPO env vars.

Phase 3: Convert Markdown Links — ✅ DONE​

Tasks​

  • 3.1 Audit markdown files for hardcoded GitHub URLs ✓
  • 3.2 Convert to relative links where possible (internal docs) ✓
  • 3.3 Document intentional main repo references ✓

Findings​

Audited all markdown files. Hardcoded URLs found are intentional:

  • Support links (Issues, Discussions) → should point to main repo
  • CLAUDE.md references → point to actual file in repo root
  • Historical/completed plans → documentation of past work

No changes needed - these correctly reference the main repository.

Phase 4: Documentation — ✅ DONE​

Tasks​

  • 4.1 Update website/README.md with Fork Compatibility section ✓
  • 4.2 Comment in docusaurus.config.ts explaining the env var pattern ✓ (added in Phase 1)

Validation​

Documentation added to README and config file.

Phase 5: Push, Merge, and Verify CI/CD — ✅ DONE​

Tasks​

  • 5.1 Create feature branch and commit all changes ✓
  • 5.2 Create PR to main ✓ (PR #16)
  • 5.3 Merge PR ✓
  • 5.4 Monitor GitHub Actions workflow ✓
  • 5.5 Verify deployed site works correctly ✓

Validation​

  • GitHub Actions workflow completes successfully
  • Deployed site loads at correct URL
  • "Edit this page" links point to correct repository
  • User confirms deployment is working

Acceptance Criteria​

  • Site builds successfully with default values (local dev)
  • Site builds successfully with custom env vars
  • GitHub Actions workflow passes env vars correctly
  • No hardcoded terchris/devcontainer-toolbox in docusaurus.config.ts
  • Documentation explains the env var pattern
  • Forking the repo results in working GitHub Pages deployment

Files to Modify​

  • website/docusaurus.config.ts
  • .github/workflows/deploy-docs.yml
  • website/README.md (create or update)
  • Various website/docs/*.md files (audit for hardcoded URLs)

Implementation Notes​

Environment Variables​

VariableDefaultDescription
GITHUB_ORGterchrisGitHub organization/username
GITHUB_REPOdevcontainer-toolboxRepository name

Local Development​

No changes needed - defaults work automatically:

cd website
npm start
# Uses terchris/devcontainer-toolbox defaults

Testing with Custom Values​

GITHUB_ORG=myorg GITHUB_REPO=myrepo npm run build

GitHub Actions Context Variables​

GitHub ContextValue
github.repository_ownerOrganization or username
github.event.repository.nameRepository name

Future: Custom Domain​

A custom domain is planned for later. When implemented:

  • url will change to the custom domain (e.g., https://devcontainer-toolbox.dev)
  • baseUrl can become / (no repo name prefix needed)
  • Environment variables can be extended: CUSTOM_DOMAIN

For now, we use GitHub Pages default URLs (username.github.io/repo-name).