Add MkDocs configuration and documentation rules for TrackGo

- Created a new `mkdocs.yml` file to define the structure and navigation for technical documentation.
- Updated `doc-updater.md` to clarify the role of the documentation specialist and the split between technical and user documentation.
- Introduced new rules in `documentation.mdc` and `technical-docs.mdc` to guide the creation of documentation, emphasizing the separation of technical and user content.
- Added a `readme.md` in the `docs` directory to provide instructions for using MkDocs with Backstage.
This commit is contained in:
shancheas
2026-09-04 15:54:39 +07:00
parent 7253dece8e
commit a6a06ae1de
5 changed files with 156 additions and 423 deletions
+24
View File
@@ -0,0 +1,24 @@
---
description: TrackGo docs split — technical MkDocs here, user VitePress in trackgo-fe/apps/docs-dev
alwaysApply: true
---
# Documentation Split
TrackGo has two documentation kinds. Sibling repos: `trackgo-be`, `trackgo-fe`, `trackgo_mobile`.
| Kind | Audience | Location | Tooling |
| --- | --- | --- | --- |
| Technical | Developers / engineers | `docs/` + `mkdocs.yml` (this repo) | MkDocs / Backstage TechDocs |
| User | Customers / operators | `trackgo-fe/apps/docs-dev/` | VitePress |
## Rules
- Technical: stack, architecture, how to run, how modules interact (backend, web, landing, mobile).
- User: features and usage (web + mobile only). Never put user how-tos in MkDocs.
- Never put tech stack / package architecture / Electron IPC in docs-dev (user docs only going forward).
- No emoji in any documentation.
- Diagrams and sequence diagrams: PlantUML fenced blocks (` ```plantuml `), not Mermaid.
- Source of truth is the codebase. If a brief disagrees with code, follow the code or label **Coming soon**. Do not invent features.
Authoring details: `.cursor/rules/technical-docs.mdc` (when editing `docs/` or `mkdocs.yml`).
+79
View File
@@ -0,0 +1,79 @@
---
description: How to write TrackGo technical docs in MkDocs (docs/ + mkdocs.yml)
globs: docs/**/*.md,mkdocs.yml
alwaysApply: false
---
# Technical Documentation (MkDocs)
Audience: developers and engineers. Location: `docs/` + `mkdocs.yml`.
## Scope
Document tech stack, architecture, how to run, and how modules interact for:
| Area | Sources |
| --- | --- |
| Backend | this repo — `src/app.module.ts`, `src/modules/` |
| Frontend web | sibling `trackgo-fe/apps/web` |
| Frontend landing | sibling `trackgo-fe/apps/landing` (public SPA, not the ERP) |
| Mobile | sibling `trackgo_mobile` |
Do **not** write customer how-tos here — those belong in `trackgo-fe/apps/docs-dev`.
## Layout
Prefer these folders under `docs/`:
```text
docs/
backend/
frontend-web/
frontend-landing/
mobile/
api.md # keep existing API reference
report-*.md # keep existing report docs
```
When adding pages:
1. Create the markdown under the matching folder.
2. Register it in `mkdocs.yml` `nav`.
3. Set `site_name` to TrackGo (it may still say `Concourse CI` — rename when you touch nav).
Preview: Docker TechDocs command in `docs/readme.md`.
## Ground in code
- Backend modules from `src/app.module.ts`: Auth, Users, Privileges, Configuration, Sales, Field, Reports.
- Web menus / RBAC keys: `trackgo-fe/apps/web/src/apps/main/layouts/data/menu.data.ts`.
- Mobile routes: `trackgo_mobile/lib/config/router.dart` (login, home, plan, customers, check-in, payment).
- Cross-read sibling repos; do not invent features. Brief vs code → follow code or **Coming soon**.
## Style
- No emoji.
- Diagrams / sequences: PlantUML only.
````markdown
```plantuml
@startuml
Alice -> Bob: request
Bob --> Alice: response
@enduml
```
````
```text
# BAD — user how-to in MkDocs
docs/how-to-create-invoice.md
# BAD — Mermaid or emoji
```mermaid
```
"🚀 Getting Started"
# GOOD
docs/backend/architecture.md
docs/frontend-web/modules.md
```