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
+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
```