Skip to main content

Documentation Website

The documentation is built with Docusaurus and hosted on GitHub Pages.

Quick Start​

All commands run inside the devcontainer:

cd /workspace/website

# Start development server (with hot reload)
npm run start -- --host 0.0.0.0

# Build for production
npm run build

# Serve production build locally (to test search)
npm run serve -- --host 0.0.0.0
important

The --host 0.0.0.0 flag is required for VS Code port forwarding to work. Without it, the server only binds to localhost inside the container.

File Structure​

website/
├── docs/                       # Documentation content (Markdown)
│   ├── index.md                # Docs home page
│   ├── getting-started.md      # Installation guide
│   ├── commands.md             # Install Tools (auto-generated)
│   ├── configuration.md        # Customization guide
│   ├── troubleshooting.md      # Troubleshooting guide
│   ├── what-are-devcontainers.md  # DevContainers explainer
│   ├── tools/                  # Tool documentation (auto-generated)
│   ├── ai-development/         # AI development guides
│   └── contributors/           # Contributor guides (you are here)
├── src/
│   ├── components/             # React components (ToolCard, ToolGrid, etc.)
│   ├── css/                    # Custom styles
│   ├── data/                   # JSON data (tools.json, categories.json)
│   ├── pages/                  # Custom pages (landing page)
│   └── utils/                  # Utility functions
├── static/
│   └── img/                    # Images, GIFs, logos, favicon
├── docusaurus.config.ts        # Main configuration
└── sidebars.ts                 # Sidebar navigation

Adding Documentation​

Adding a New Page​

  1. Create a Markdown file in the appropriate folder under docs/
  2. Add frontmatter at the top:
---
title: Page Title
sidebar_position: 5
---

# Page Title

Your content here...
  1. The page will automatically appear in the sidebar

Adding a New Section​

  1. Create a folder under docs/ (e.g., docs/new-section/)
  2. Add a _category_.json file:
{
  "label": "New Section",
  "position": 5,
  "link": {
    "type": "doc",
    "id": "new-section/index"
  }
}
  1. Create an index.md as the section's landing page

Auto-Generated Pages​

Some pages are auto-generated by dev-docs:

PageGenerated From
docs/tools/index.mdInstall script metadata
docs/tools-details.mdInstall script --help output
docs/commands.mdManage script metadata
caution

Don't manually edit auto-generated pages. Your changes will be overwritten when dev-docs runs.

To regenerate:

dev-docs

The site uses local search (docusaurus-search-local).

  • Search index is built during npm run build
  • In dev mode (npm run start), search shows a warning - this is normal
  • To test search locally, use npm run build then npm run serve

Deployment​

The site deploys automatically via GitHub Actions when changes to website/ are pushed to main.

Workflow: .github/workflows/deploy-docs.yml

URL: https://dct.sovereignsky.no/

To manually trigger a deploy:

  1. Go to Actions → "Deploy Documentation"
  2. Click "Run workflow"

Common Tasks​

Update the Landing Page​

Edit src/pages/index.tsx and components in src/components/.

Change Theme Colors​

Edit src/css/custom.css.

Add Images​

  1. Place images in static/img/
  2. Reference as /img/filename.png in Markdown

The build fails on broken links (onBrokenLinks: 'throw' in config). Run npm run build to check for issues before pushing.

Troubleshooting​

Server not accessible from browser​

Make sure you're using --host 0.0.0.0:

npm run start -- --host 0.0.0.0

New folder not showing in sidebar​

Restart the dev server. Hot reload doesn't detect new folders.

Search not working in dev mode​

This is expected. Search only works after npm run build. Use npm run serve to test search locally.

Check the error message for the specific broken link and fix it. Common issues:

  • Typos in links
  • Deleted pages still referenced
  • Wrong anchor format (use lowercase, dashes instead of spaces)