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:
@@ -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`).
|
||||
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user