Docs

Documentation for self-hosting TrackGeek, from installation to everyday management.

About

TrackGeek Docs is the documentation website for running TrackGeek on your own hardware. It provides English guides for installation, configuration, service credentials, updates, backups, troubleshooting and API Reference.

Self-hosting instructions follow the installer README. Credential guides use official provider documentation and TrackGeek's API configuration.

Features

Documentation

• Installation instructions for Linux, macOS, and Windows;
• Configuration, networking, management commands, updates, automatic startup, and backups;
• Credential guides for sign-in providers, Discord bots, media services, Resend, and Stripe;
• Markdown articles with code highlighting, copy buttons, and an on-page table of contents;
• Direct links to edit articles or report documentation issues on TrackGeek/docs.

Navigation

• Generated route tree with typed article parameters and Zod search validation;
• Article loaders, intent preloading, automatic code splitting, and loading/error boundaries;
• Shareable search and operating-system selection through URL parameters;
• Responsive navigation and light/dark themes.

Tech Stack

Category	Technology
UI	React 19
Language	TypeScript 7
Build	Vite 8
Routing	TanStack Router 1
Styling	Tailwind CSS 4
Components	shadcn/ui + @jalco
Validation	Zod 4
Content	Markdown, react-markdown, remark-gfm
Code highlighting	Shiki
Linting / Formatting	Biome 2
Testing	Bun test, Playwright
Package manager	Bun

Project Structure

src/
├── components/
│   ├── docs/
│   ├── jalco/
│   ├── layout/
│   └── ui/
├── constants/
├── content/
│   ├── api-reference/
│   └── self-hosting/
├── hooks/
├── routes/
│   ├── __root.tsx
│   ├── $slug.tsx
│   ├── api-reference.tsx
│   ├── api-reference_.$slug.tsx
│   └── index.tsx
├── styles/
├── types/
├── utils/
├── main.tsx
├── router.ts
└── routeTree.gen.ts
public/
tests/
biome.json
playwright.config.ts
vite.config.ts

Routes compose the page sections directly. Components, hooks, constants, and utilities stay in their respective directories. routeTree.gen.ts is generated by TanStack Router and must not be edited manually.

Run Locally

Prerequisites: Bun and a Node.js version supported by Vite (^20.19.0 || >=22.12.0).

Clone the project:

git clone https://github.com/TrackGeek/docs.git
cd docs

Install dependencies:

bun install

Start the development server:

bun run dev

Open the local URL printed by Vite, normally http://localhost:5173. The home route redirects to /introduction.

Running this documentation site does not require Docker, a database, or the API credentials described in its articles.

Scripts

Script	Description
bun run dev	Start the development server with hot reload
bun run generate	Generate the TanStack Router route tree
bun run typecheck	Generate routes and check TypeScript
bun run build	Generate routes, check types, and build for production
bun run preview	Preview the production build locally
bun run check	Check formatting, lint rules, and imports with Biome; fail on warnings
bun run check:fix	Apply formatting, import sorting, and safe lint fixes
bun run lint	Run Biome lint checks; fail on warnings
bun run lint:fix	Apply safe lint fixes
bun run format	Check formatting with Biome
bun run format:fix	Format supported files with Biome
bun run test	Run unit tests with Bun
bun run test:e2e	Run browser tests against the production build

Biome follows the Git ignore rules and excludes the generated route tree. It checks supported source and configuration files, including Tailwind CSS. Scoped rule exceptions preserve the registry components' static rendering patterns and reduced-motion overrides.

Testing

Run code checks and unit tests:

bun run check
bun run typecheck
bun run test

Install Chromium, build the site, and run browser tests:

bunx playwright install chromium
bun run build
bun run test:e2e

Playwright starts a preview server automatically. Browser tests cover navigation, URL state, credential links, code copying, themes, mobile layouts, preloading, and loading/error boundaries.

Editing Content

Articles live in src/content/self-hosting/. To add an article:

1. Create its Markdown file in that directory.
2. Add its slug to src/utils/docs-schemas.ts.
3. Add its navigation and search metadata to src/constants/docs.ts.
4. Run the checks and tests before submitting the change.

Use root-relative article links such as /installation or /media-credentials#tmdb. Articles use /$slug, without a /docs/ prefix. Search uses q; installation tabs use os, with linux, macos, or windows. For example: /installation?os=windows and /introduction?q=Docker.

Keep installation commands in src/constants/installation.ts aligned with the self-hosting README. Keep credential callbacks and Stripe webhook events aligned with the TrackGeek API. Do not invent requirements, recovery procedures, or API contracts that the source projects do not document.

Theme tokens live in src/styles/globals.css. Registry components live in src/components/jalco/; CodeBlock is adapted for browser-compatible React with lazy Shiki highlighting. Third-party attribution is recorded in THIRD-PARTY-NOTICES.md.

Deployment

Build the site:

bun run build

Publish the dist/ directory to a static host. Configure an SPA fallback so direct visits to paths such as /installation serve index.html. A fallback for hosts that support _redirects is included in public/_redirects.

Use bun run preview to inspect the production build locally before publishing.

Contributing

See the contribution guidelines before opening a pull request on TrackGeek/docs.

API Reference

The published reference starts at /api-reference. Markdown lives in src/content/api-reference/; article metadata lives in src/constants/docs.ts. It covers OAuth application registration, Authorization Code with PKCE, REST tracking endpoints, MCP connection and tools, and error handling. Examples use https://api.trackgeek.net.