docs: add a documentation site published to GitHub Pages

.github/workflows/build.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Type Check
         run: npm run check-types
 
+      - name: Documentation up to date
+        run: npm run docs:check
+
       - name: Lint
         run: npm run lint
 

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+  schedule:
+    # Weekly, to catch links to other websites that went dead.
+    - cron: "41 5 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Docs
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    # The build, the checks and the deployment are shared by all the documentation sites.
+    uses: boxboxjason/hugo-theme/.github/workflows/docs.yml@089035183ff3ce6abed590404e87faf86037af14 # main, same commit as docs/go.mod
+    with:
+      deploy: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
+      check-external-links: ${{ github.event_name == 'schedule' }}

CONTRIBUTING.md

@@ -127,6 +127,16 @@ These are the most useful scripts from [package.json](package.json):
    - Reference the issue number (e.g. `Fixes #123`).
    - Describe what changed and how it was tested.
 
+## Documentation
+
+The documentation lives in the [`docs`](docs) directory, as Markdown rendered by [Hugo](https://gohugo.io/) (extended edition) with the shared [hugo-theme](https://github.com/boxboxjason/hugo-theme), and is published to <https://boxboxjason.github.io/achievements/> from `main`.
+
+- Change the documentation in the same pull request as the code it describes.
+- The [commands](docs/content/docs/commands.md), [settings](docs/content/docs/settings.md) and [achievements](docs/content/docs/achievements.md) pages are generated from `package.json` and the achievement templates: run `npm run docs:generate` after changing them, and commit the result. CI runs `npm run docs:check`, which fails when a generated page is stale.
+- The getting started walkthrough shown in VS Code ([docs/walkthroughs](docs/walkthroughs)) is also rendered on the site: edit it in one place.
+- `hugo server --source docs` serves the site locally with live reload, `hugo --source docs` builds it into `docs/public`.
+- Look and feel (colors, footer, ...) belong to the shared theme, do not restyle a single site.
+
 ## Coding guidelines
 
 - Keep changes scoped to the issue.

README.md

@@ -23,131 +23,20 @@ Achievements is a Visual Studio Code extension that allows you to track your pro
 - Enable or disable notifications
 - Enable or disable any type of listeners for **privacy**
 
-## How it works
+## Documentation
 
-- The extension activates on `onStartupFinished` and listens to VS Code and Git events (based on your settings).
-- Progress and achievement state are stored locally in a SQLite database powered by `sql.js` (no server).
-- The UI is a VS Code webview (React) opened via **Achievements: Show**.
+📖 **<https://boxboxjason.github.io/achievements/>**
 
-### Local data & read-only mode
+The documentation covers [installation](https://boxboxjason.github.io/achievements/docs/installation/), [getting started](https://boxboxjason.github.io/achievements/docs/getting-started/), [how it works](https://boxboxjason.github.io/achievements/docs/how-it-works/) (local data, devcontainers, network access), the full list of [achievements](https://boxboxjason.github.io/achievements/docs/achievements/), [commands](https://boxboxjason.github.io/achievements/docs/commands/) and [settings](https://boxboxjason.github.io/achievements/docs/settings/).
 
-- Data is stored under VS Code's global storage as `achievements.sqlite`.
-- A lock prevents multiple VS Code instances from writing the database at the same time.
-  - If another instance is using the DB, the extension runs in **read-only** mode: listeners are disabled and a status bar item indicates the state.
+## Privacy
 
-### Sharing progress across devcontainers
-
-When VS Code connects to a devcontainer, `achievements.sqlite` is stored inside the container's filesystem, at a path determined by the extension ID: `~/.vscode-server/data/User/globalStorage/boxboxjason.achievements/achievements.sqlite`
-
-That path is deterministic across every devcontainer you connect to, so you can persist and share progress between containers (and across rebuilds) by mounting a host directory or named Docker volume at that exact location in `.devcontainer/devcontainer.json`:
-
-```jsonc
-{
-  "mounts": [
-    "source=${localEnv:HOME}/.achievements-data,target=/home/vscode/.vscode-server/data/User/globalStorage/boxboxjason.achievements,type=bind"
-  ]
-}
-```
-
-Adjust the remote user's home directory in `target` to match your container image (e.g. `/root` instead of `/home/vscode`), and use the same `source` across devcontainer configs to share one database between all of them.
-
-> **Note:** only open one devcontainer at a time against a shared database. The write lock file
-> lives under the container's own temp directory rather than next to the database, so two
-> containers open simultaneously against the same mounted database won't see each other's lock
-> and could both attempt to write at once.
-
-### Network access
-
-By default, this extension makes **no network requests** and works fully offline.
-
-The only exception is the optional `achievements.checkOutdatedExtensions` setting (disabled by default). When enabled, it periodically sends the IDs of your installed (non-builtin) extensions to the VS Marketplace (`marketplace.visualstudio.com`) to check for outdated versions and award related achievements. Enable it only if you're comfortable sharing your installed-extension list with the Marketplace.
-
-## Extension Commands
-
-Several commands are available to interact with the Achievements extension. You can access these commands through the Command Palette (Ctrl+Shift+P) or by using keybindings.
-
-|Command|Description|
-|---|---|
-|`achievements.enable`|Enable or Disable the Achievements extension event tracking (requires a restart)|
-|`achievements.settings`|Open the Achievements configuration page|
-|`achievements.show`|Show the Achievements panel|
-
-## Configuration
-
-The Achievements extension can be configured through the settings. You can access the settings by going to **File > Preferences > Settings** and searching for "Achievements".
-You can also access the settings by using the command `achievements.settings`.
-
-|Setting|Description|
-|---|---|
-|`achievements.enabled`|Enable or disable the Achievements extension event tracking|
-|`achievements.notifications`|Enable or disable notifications for achievements|
-|`achievements.logDirectory`|Select the directory where the log files will be stored|
-|`achievements.logLevel`|Select the log level (info, debug, error)|
-|`achievements.username`|Define your username for the Achievements score display|
-|`achievements.listeners.debug`|Enable or disable debug listeners|
-|`achievements.listeners.git`|Enable or disable git listeners|
-|`achievements.listeners.extensions`|Enable or disable extension listeners|
-|`achievements.checkOutdatedExtensions`|Opt-in: check installed extensions against the VS Marketplace for outdated versions (sends your installed extension IDs over the network; disabled by default)|
-|`achievements.listeners.files`|Enable or disable file listeners|
-|`achievements.listeners.shortcuts`|Enable or disable paste shortcut listeners|
-|`achievements.listeners.tabs`|Enable or disable tab listeners|
-|`achievements.listeners.tasks`|Enable or disable task listeners|
-|`achievements.listeners.time`|Enable or disable time tracking listeners|
-|`achievements.ignore.files`|List of file names ignored by file-based achievements (case-insensitive, for example `package-lock.json` matches `PACKAGE-LOCK.JSON`)|
-|`achievements.ignore.directories`|List of directory names ignored by file-based achievements (case-sensitive, for example `.git` matches only `.git`)|
+Progress is stored locally in a SQLite database, and by default this extension makes **no network requests**. The only exception is the opt-in `achievements.checkOutdatedExtensions` setting, which sends the IDs of your installed extensions to the VS Marketplace to check for outdated versions. Every listener can be turned off individually in the settings.
 
 ## Installation
 
-### From OpenVSX
-
-1. Download and install [Visual Studio Code](https://code.visualstudio.com/).
-2. Download and install the [Achievements Extension VSIX](https://open-vsx.org/extension/boxboxjason/achievements) from the OpenVSX registry.
-3. Open Visual Studio Code. Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing `Ctrl+Shift+X`.
-4. Click on the three-dot menu icon in the top-right corner of the Extensions view and select "Install from VSIX...".
-5. In the file dialog that appears, navigate to the location where you downloaded the Achievements Extension VSIX file, select it, and click "Open".
-6. Visual Studio Code will install the extension. Once the installation is complete, you may need to reload Visual Studio Code for the extension to be activated. You can do this by clicking the "Reload" button that appears in the Extensions view after installation or by closing and reopening Visual Studio Code.
-7. Run the command `Achievements: Show` from the Command Palette (`Ctrl+Shift+P`) to open the Achievements panel.
-
-### From VSIX
-
-1. Download and install [Visual Studio Code](https://code.visualstudio.com/).
-2. Download and install the [Achievements Extension VSIX](https://github.com/boxboxjason/achievements/releases) from the GitHub releases page.
-3. Open Visual Studio Code. Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing `Ctrl+Shift+X`.
-4. Click on the three-dot menu icon in the top-right corner of the Extensions view and select "Install from VSIX...".
-5. In the file dialog that appears, navigate to the location where you downloaded the Achievements Extension VSIX file, select it, and click "Open".
-6. Visual Studio Code will install the extension. Once the installation is complete, you may need to reload Visual Studio Code for the extension to be activated. You can do this by clicking the "Reload" button that appears in the Extensions view after installation or by closing and reopening Visual Studio Code.
-7. Run the command `Achievements: Show` from the Command Palette (`Ctrl+Shift+P`) to open the Achievements panel.
+Install it from [Open VSX](https://open-vsx.org/extension/boxboxjason/achievements), or download the VSIX from the [GitHub releases](https://github.com/boxboxjason/achievements/releases) and run **Extensions: Install from VSIX...**. Then run **Achievements: Show** from the Command Palette (`Ctrl+Shift+P`).
 
 ## Development
 
-Prerequisites:
-
-- Node.js `24` (matches CI)
-- npm
-- VS Code
-
-Quick start:
-
-1. Install dependencies: `npm ci`
-2. Open in VS Code: `code .`
-3. Press `F5` (launches the Extension Development Host)
-
-Build system notes:
-
-- The default debug launch runs the VS Code task `watch` (see [.vscode/tasks.json](.vscode/tasks.json)).
-  - `watch:esbuild` bundles the extension + webview.
-  - `watch:tsc` type-checks in watch mode.
-
-Useful scripts:
-
-|Command|Description|
-|---|---|
-|`npm run compile`|Clean + build Tailwind + bundle extension/webview (dev build)|
-|`npm run build`|Production build (typecheck + lint + minified bundle)|
-|`npm test`|Compile with `tsc` and run extension tests via `@vscode/test-cli`|
-|`npm run test:coverage`|Run tests with NYC coverage output|
-|`npm run lint`|Lint `src/`|
-|`npm run check-types`|Typecheck only (`tsc --noEmit`)|
-|`npm run package`|Build and create a `.vsix` via `vsce`|
-
-Contributing guidelines: see [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) to build, test and package the extension, and to work on the documentation.

docs/.gitignore

@@ -0,0 +1,3 @@
+public/
+resources/
+.hugo_build.lock

docs/content/_index.md

@@ -0,0 +1,33 @@
+---
+title: Achievements
+layout: hextra-home
+---
+
+{{< hextra/hero-headline >}}
+  Earn achievements while you code
+{{< /hextra/hero-headline >}}
+
+{{< hextra/hero-subtitle >}}
+  A VS Code extension that tracks your coding journey and rewards it, entirely offline.
+{{< /hextra/hero-subtitle >}}
+
+{{< spacer >}}
+
+{{< hextra/hero-button text="Get started" link="docs/installation" >}}
+
+{{< spacer "3rem" >}}
+
+{{< hextra/feature-grid >}}
+  {{< hextra/feature-card
+    title="Nothing to trigger"
+    subtitle="Achievements unlock from what you already do: saving files, committing, switching tabs, running tasks, fixing errors, and more."
+  >}}
+  {{< hextra/feature-card
+    title="Private by default"
+    subtitle="Progress lives in a local SQLite database, no network request is made unless you opt in, and every listener can be turned off."
+  >}}
+  {{< hextra/feature-card
+    title="Your profile"
+    subtitle="Follow your completion percentage, the time spent coding, and the progress towards every achievement in one panel."
+  >}}
+{{< /hextra/feature-grid >}}

docs/content/docs/_index.md

@@ -0,0 +1,37 @@
+---
+title: Documentation
+weight: 1
+---
+
+Achievements is a Visual Studio Code extension that allows you to track your progress in coding, and earn achievements for completing tasks.
+
+![The Achievements panel](../images/achievements.gif)
+
+{{< callout type="warning" >}}
+This extension is in beta, may contain bugs and database schema may change in future versions.
+It is recommended to back up your data before updating.
+{{< /callout >}}
+
+## Features
+
+- Track your progress in coding
+- Earn achievements for completing tasks
+- View your achievements in the **Achievements** panel
+- View each achievement's description and requirements
+- View your progress towards each achievement
+- Track your time spent coding
+- Filter achievements by category, progress, and name
+- View your profile and completion percentage
+- Enable or disable notifications
+- Enable or disable any type of listeners for **privacy**
+
+## Where to go next
+
+{{< cards >}}
+  {{< card link="installation" title="Installation" subtitle="From Open VSX or from a VSIX file." >}}
+  {{< card link="getting-started" title="Getting started" subtitle="Open the panel, set your username, choose what gets tracked." >}}
+  {{< card link="how-it-works" title="How it works" subtitle="Local data, read-only mode, devcontainers and network access." >}}
+  {{< card link="achievements" title="Achievements" subtitle="Every achievement and what it takes to unlock it." >}}
+  {{< card link="commands" title="Commands" subtitle="The commands available from the Command Palette." >}}
+  {{< card link="settings" title="Settings" subtitle="Every setting, with its default value." >}}
+{{< /cards >}}

docs/content/docs/achievements.md

@@ -0,0 +1,65 @@
+---
+title: Achievements
+weight: 40
+---
+
+<!-- Code generated by scripts/generate-docs.ts (run `npm run docs:generate`); DO NOT EDIT. -->
+
+Every achievement comes in tiers: each tier raises the required value N, and earns more experience.
+
+Rows with `<language>` exist once per tracked language: `ada`, `assembly`, `c`, `c#`, `c++`, `cobol`, `css`, `fortran`, `go`, `haskell`, `html`, `java`, `javascript`, `kotlin`, `less`, `lua`, `markdown`, `matlab`, `objective-c`, `pascal`, `perl`, `php`, `powershell`, `python`, `r`, `react`, `ruby`, `rust`, `scala`, `scss`, `shell`, `sql`, `swift`, `toml`, `typescript`, `vue`, `yaml`.
+
+## Productivity
+
+| Achievements | Group | Requirement | Required N |
+| ------------ | ----- | ----------- | ---------- |
+| Code Monkey 1 … Code Monkey 11 | Lines of Code | Write N lines of code | 1 → 10,000,000,000 (11 tiers) |
+| `<language>` Speaker 1 … `<language>` Speaker 16 | Lines of Code | Write N lines of `<language>` code | 2 → 100,000,000 (16 tiers) |
+| Outstanding Commentator 1 … Outstanding Commentator 16 | Lines of Comments | Write N lines of comments | 2 → 100,000,000 (16 tiers) |
+| Copy Ninja 1 … Copy Ninja 16 | Number of Pastes | Paste N times | 1 → 50,000,000 (16 tiers) |
+| I can fix her 1 … I can fix her 16 | Errors Fixed | Fix N errors | 1 → 50,000,000 (16 tiers) |
+| Shower Avoider 1 … Shower Avoider 14 | time spent | Spend N hours coding | 1 → 1,000,000 (14 tiers) |
+| Tab Hoarder 1 … Tab Hoarder 6 | Number of Simultaneous Tabs | Open N tabs simultaneously | 1 → 100 (6 tiers) |
+| Split Personality 1 … Split Personality 6 | Number of Simultaneous Editor Groups | Open N editor groups simultaneously | 1 → 100 (6 tiers) |
+| Multi-tasker 1 … Multi-tasker 6 | Number of Simultaneous Workspace Folders | Open N workspace folders simultaneously | 1 → 100 (6 tiers) |
+| Remote Worker 1 … Remote Worker 14 | time spent | Spend N hours coding remotely | 1 → 1,000,000 (14 tiers) |
+| Hydra Editing 1 … Hydra Editing 11 | Multi Cursor Sessions | Start multi-cursor editing N times | 1 → 100,000 (11 tiers) |
+| Night Owl 1 … Night Owl 11 | Night Owl Sessions | Start N coding sessions late at night | 1 → 50,000 (11 tiers) |
+| Early Bird 1 … Early Bird 11 | Early Bird Sessions | Start N coding sessions early in the morning | 1 → 50,000 (11 tiers) |
+| Connection Streak 1 … Connection Streak 1000 | Connection Streak | Connect for N consecutive days | 1 → 1,000 (1000 tiers) |
+
+## Git
+
+| Achievements | Group | Requirement | Required N |
+| ------------ | ----- | ----------- | ---------- |
+| Committer 1 … Committer 11 | Commits | Commit N times | 1 → 100,000 (11 tiers) |
+| Friend of the Trees 1 … Friend of the Trees 11 | Branches Created | Create N branches | 1 → 50,000 (11 tiers) |
+| Merger 1 … Merger 11 | Merges and Rebases | Merge or rebase N times | 1 → 50,000 (11 tiers) |
+| Amender 1 … Amender 11 | Amends | Amend N times | 1 → 50,000 (11 tiers) |
+| Product Shipping 1 … Product Shipping 11 | Pushes | Push N times | 1 → 50,000 (11 tiers) |
+
+## VS Code
+
+| Achievements | Group | Requirement | Required N |
+| ------------ | ----- | ----------- | ---------- |
+| Buying Frenzy 1 … Buying Frenzy 6 | Extensions Installed | Install N extensions | 1 → 100 (6 tiers) |
+| Living Dangerously 1 … Living Dangerously 6 | Extensions Outdated | Have N outdated extensions | 1 → 100 (6 tiers) |
+| Pimp my Ride 1 … Pimp my Ride 6 | Themes Installed | Install N themes | 1 → 100 (6 tiers) |
+| Chameleon 1 … Chameleon 9 | Theme Changed | Change theme N times | 1 → 5,000 (9 tiers) |
+| Am I better than everyone ? 1 … Am I better than everyone ? 11 | Debugger Sessions | Start N debugger sessions | 1 → 50,000 (11 tiers) |
+| Breaking Bad 1 … Breaking Bad 11 | Breakpoints | Create N breakpoints | 1 → 100,000 (11 tiers) |
+| Commander 1 … Commander 11 | tasks | Run N vscode tasks (terminal commands) | 1 → 50,000 (11 tiers) |
+| Failure achiever 1 … Failure achiever 11 | tasks | Run N failing vscode tasks or terminal command | 1 → 50,000 (11 tiers) |
+| Works on my Machine 1 … Works on my Machine 11 | tasks | Run N successful vscode tasks or terminal command | 1 → 50,000 (11 tiers) |
+| Portal Opener 1 … Portal Opener 11 | Terminals Opened | Open N terminals | 1 → 50,000 (11 tiers) |
+| Snippets Master 1 … Snippets Master 11 | Code Snippets | Use N code snippets | 1 → 50,000 (11 tiers) |
+
+## Files
+
+| Achievements | Group | Requirement | Required N |
+| ------------ | ----- | ----------- | ---------- |
+| Creator 1 … Creator 16 | Files Created | Create N files | 2 → 100,000,000 (16 tiers) |
+| `<language>` Creator 1 … `<language>` Creator 12 | Files Created | Create N files in `<language>` | 1 → 500,000 (12 tiers) |
+| Please Bro, Just One more Refactor 1 … Please Bro, Just One more Refactor 11 | Files Renamed | Rename or Move N files | 1 → 50,000 (11 tiers) |
+| Shaper 1 … Shaper 11 | Resource Created | Create N directories | 1 → 50,000 (11 tiers) |
+| Destroyer 1 … Destroyer 11 | Resource Deleted | Delete N files or directories | 1 → 50,000 (11 tiers) |