106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# Homarr Documentation (`@homarr/docs`)
|
|
|
|
The official [homarr.dev](https://homarr.dev) documentation site, built with [Docusaurus 3](https://docusaurus.io/) and living inside the Homarr monorepo.
|
|
|
|
## Why it's in the monorepo
|
|
|
|
Having documentation alongside the application code enables:
|
|
|
|
- **Two-way linking** — the docs app imports from `@homarr/definitions` for type-safe integration/widget metadata, and the main app references doc paths via generated sitemap types
|
|
- **Atomic PRs** — code changes and their documentation updates ship in the same pull request
|
|
- **Shared tooling** — same Node version, pnpm catalog, oxlint/oxfmt, CI pipeline
|
|
- **Build-time validation** — Docusaurus strict mode catches broken links and references at build time
|
|
|
|
## Development
|
|
|
|
From the **monorepo root**:
|
|
|
|
```bash
|
|
# Start the docs dev server (port 3003)
|
|
pnpm dev:docs
|
|
|
|
# Or from within this directory
|
|
pnpm dev
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
# Build docs only
|
|
pnpm turbo build --filter=@homarr/docs
|
|
|
|
# Build everything (docs + main app + tasks + websocket)
|
|
pnpm build
|
|
```
|
|
|
|
## Lint & Format
|
|
|
|
Uses oxlint and oxfmt (same as the rest of the monorepo):
|
|
|
|
```bash
|
|
pnpm lint # oxlint
|
|
pnpm format # oxfmt (check)
|
|
pnpm format -- --write # oxfmt (fix)
|
|
```
|
|
|
|
## Typecheck
|
|
|
|
```bash
|
|
pnpm typecheck
|
|
```
|
|
|
|
## Content Structure
|
|
|
|
```
|
|
docs/
|
|
├── getting-started/ # Installation guides, glossary, prerequisites
|
|
├── management/ # Boards, apps, users, integrations, settings, tasks, API
|
|
├── integrations/ # 55 integration guides (one folder each)
|
|
├── widgets/ # 42 widget guides (one folder each)
|
|
├── advanced/ # SSO, env vars, proxy, styling, CLI, development
|
|
└── community/ # FAQ, donate, license, translations, get-in-touch
|
|
```
|
|
|
|
Each integration/widget doc follows a consistent pattern:
|
|
|
|
- `index.ts` — typed metadata (`IntegrationDefinition` / `WidgetDefinition`)
|
|
- `index.mdx` — content using shared React components (`IntegrationHeader`, `WidgetHeader`, etc.)
|
|
|
|
## Importing from homarr packages
|
|
|
|
The docs app has `@homarr/definitions` as a workspace dependency. You can import integration kinds, widget kinds, and other definitions directly:
|
|
|
|
```typescript
|
|
import { IntegrationKind } from "@homarr/definitions";
|
|
```
|
|
|
|
This enables type-safe references to homarr domain concepts within documentation code.
|
|
|
|
## Search (Algolia DocSearch)
|
|
|
|
Search uses the `Docusaurus` Algolia index (crawler `cd77a285-2756-4557-bf21-ee703748df15`). A separate `markdown` index is built for LLM markdown indexing.
|
|
|
|
Crawler reference config: [`docsearch.config.js`](docsearch.config.js).
|
|
|
|
**Verify search health:**
|
|
|
|
```bash
|
|
pnpm verify:search
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
| -------------- | ------------------------------------------- |
|
|
| Site generator | Docusaurus 3 (`@docusaurus/preset-classic`) |
|
|
| Styling | Tailwind CSS 3 + Docusaurus Infima |
|
|
| Icons | `@tabler/icons-react` |
|
|
| Diagrams | Mermaid (`@docusaurus/theme-mermaid`) |
|
|
| Search | Algolia DocSearch |
|
|
| Analytics | PostHog |
|
|
| Charts | @nivo/line |
|
|
|
|
## Contributing
|
|
|
|
When making changes to the homarr codebase that affect user-facing behavior, **always update the corresponding documentation in this app**. See `.cursor/rules/documentation-sync.mdc` for the complete mapping of code changes to doc locations.
|