Quickstart

Every snippet below is copy-paste ready. The exampleSite/ in the theme repository is this exact setup, fully assembled.

1. Configure Hugo

Copy the output-format blocks from Hugo configuration into your hugo.toml and set your baseURL. Deploying under a sub-path (GitHub/GitLab Pages) only requires changing baseURL.

2. Create site.json

Minimal version (full key reference here):

{
  "title": "My Product Docs",
  "defaultLanguage": "en",
  "themes": [
    { "id": "light", "label": "Light", "dark": false, "default": true },
    { "id": "dark",  "label": "Dark",  "dark": true,  "default": true }
  ]
}

3. Create the content tree

You always write under one fixed directory called the working-docs token, with a language directory below it: docs/<token>/<language>/…. Versions are created later from git tags (versioning).

The token is yours to choose. This site uses __vcurrent__, the snippets below use __mydocs__. Pick a string that will never occur naturally in your content, because releasing literally string-replaces it in links. If it contains capitals, set disablePathToLower = true in hugo.toml.

Every level gets an _index.md:

content/
└── docs/
    ├── _index.md                  ← title: "Documentation"
    └── __mydocs__/                    ← your token
        ├── _index.md              ← title: "__mydocs__" (the literal token)
        └── en/
            ├── _index.md          ← title: "English"
            └── getting-started/
                ├── _index.md      ← title + description + weight
                └── hello.md

---
title: "Getting Started"
description: "Install and run the product."
weight: 1
---

weight orders sections and pages in the sidebar. description shows on section cards, in search results and in link previews.

4. Add the version manifest (for local development)

In production this file is generated by the release pipeline from your git tags. Commit a minimal one so the pickers work while writing locally:

{
  "versions": [
    {
      "id": "__mydocs__", "label": "__mydocs__", "path": "/docs/__mydocs__/", "latest": true,
      "languages": [
        { "code": "en", "label": "EN", "path": "/docs/__mydocs__/en/", "default": true }
      ]
    }
  ]
}

It drives the version/language pickers, search scoping and the outdated-version banner.

5. Run

hugo server

Note

site.json and static/versions.json are not watched by the dev server. Restart hugo server after editing them.

You now have: a themed homepage at /, your docs under docs/__mydocs__/en/, working search (Ctrl/⌘ K), light/dark switching and a styled 404. Releasing versions from tags is covered in versioning. Next up: writing pages.