Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s
All checks were successful
Test / test (push) Successful in 2s
This commit is contained in:
34
AGENTS.md
34
AGENTS.md
@@ -10,11 +10,11 @@ Free/open-source helper for tabletop RPG campaigns (campaigns, markdown notes, f
|
||||
items, maps, dice widgets, sounds).
|
||||
|
||||
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth, CommonJS, entry `src/index.js`.
|
||||
- `frontend/` — **Nuxt 4 / Vue 3** (`<script setup>`), SCSS, axios, marked, mitt, motion, entry `app/app.vue`. No routed pages (§5.1).
|
||||
- `frontend/` — **Nuxt 4 / Vue 3** (`<script setup>`), SCSS, axios, marked, mitt, motion, entry `app/app.vue`. Two pages: the app and `/docs` (§5.1).
|
||||
- `discord-bot/` — Discord bot (slash commands) that talks to the backend with a shared service secret, no login.
|
||||
- `dragonroll-foundry/` — Foundry VTT module (`scripts/api.js`) + optional read-only snapshot bridge.
|
||||
- `obsidian-plugin/` — plain JavaScript Obsidian plugin that imports/pushes campaign notes.
|
||||
- `tests/` — `npm test` (`node --test`, no dependencies installed): Foundry sync toggle and pairing status, map pins and tokens, sidebar entries.
|
||||
- `tests/` — `npm test` (`node --test`, no dependencies installed): Foundry sync toggle and pairing status, map pins and tokens, sidebar entries, the `/docs` pages.
|
||||
|
||||
No DB seeding, no migrations, no linter/formatter, no Pinia/Vuex. Git: default branch `master` on a
|
||||
self-hosted Gitea; `.gitea/workflows/deploy.yml` builds and deploys Docker images on push to `master`,
|
||||
@@ -125,13 +125,24 @@ the JWT guard; CORS opened for it): `snapshot` (actors + world items, `fullSync`
|
||||
|
||||
## 5. Frontend
|
||||
|
||||
### 5.1 Not a routed app
|
||||
### 5.1 Two pages: the app and the documentation
|
||||
|
||||
There is no `app/pages/`. `app/app.vue` renders a shell of managers (`Window`, `Content`, `Toast`,
|
||||
`Tooltip`, `ContextMenu`) and boots: `GetUser()` (JWT in localStorage) → `RestoreCampaign()` or open
|
||||
`main_menu`; no user → `HasAdmin() ? 'login' : 'register' {firstTime:true}`. The one real URL is
|
||||
`/link/authorize` (and the legacy `/discord/authorize`), which renders the service link screen instead
|
||||
of the app.
|
||||
`app/pages/` routes the only two things the frontend is. `index.vue` and the `[...all].vue` catch-all
|
||||
both render `components/views/AppShell.vue` — the window app, which has no routes of its own — and
|
||||
`docs/index.vue` + `docs/[slug].vue` render `views/DocsView.vue`, the documentation at `/docs`.
|
||||
`app.vue` holds only what is site-wide (the head, the theme) and `<NuxtPage>`. AppShell boots:
|
||||
`GetUser()` (JWT in localStorage) → `RestoreCampaign()` or open `main_menu`; no user →
|
||||
`HasAdmin() ? 'login' : 'register' {firstTime:true}`. `/link/authorize` (and the legacy
|
||||
`/discord/authorize`) is not a page either: AppShell checks the path and renders the service link
|
||||
screen instead of the app.
|
||||
|
||||
The documentation is markdown files under `app/content/docs/<group>/<NN>-<page>.md`: the folder is the
|
||||
sidebar group and its number orders the groups, the file's number orders its pages, the rest of its
|
||||
name is the slug, and the first heading is the title. `services/Docs.js` reads them
|
||||
(`import.meta.glob(..., {query:'?raw'})`), builds the sidebar and renders a page with marked;
|
||||
`services/DocsMarkdown.js` holds the heading/slug helpers the sidebar and the anchors share and imports
|
||||
nothing so `tests/docs.test.js` can load it. A new group's label goes in `docs.json` under
|
||||
`groups.<folder>` **in all three locales**. The first page is served at `/docs` itself.
|
||||
|
||||
Two kinds of screens: **windows** (floating draggable/resizable overlays) and **content** — the
|
||||
campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`), turned on when
|
||||
@@ -166,7 +177,7 @@ writes `localStorage.selectedCampaignId`, `RestoreCampaign`), `Content.js` (§5.
|
||||
(`mitt()` bus), `Toaster.js`, `Tooltip.js`, `ContextMenu.js`, `Sound.js` (`AddSound` binds
|
||||
`snap.wav` to `.sound-click`), `Marker.js` (marked + widgets), `ActionRegistry.js` (command palette:
|
||||
`register/unregister/search/execute`), `Windows.js` / `WindowDefinitions.js`, `MapPins.js`, `MapTokens.js`,
|
||||
`widgets/DiceParser.js`.
|
||||
`Docs.js` + `DocsMarkdown.js` (§5.1), `widgets/DiceParser.js`.
|
||||
|
||||
### 5.4 Markdown → widgets
|
||||
|
||||
@@ -199,7 +210,9 @@ variables: always style with `var(--color-…)`, never hardcode hex, and add a n
|
||||
i18n: `frontend/i18n/locales/<lang>/<namespace>.json` for `en` (default), `es`, `ca`; `plugins/i18n.ts`
|
||||
nests each file under its filename, so the key is `<file>.<path>` (`$t('windows.login')`). **Add every
|
||||
new string to all three locales.** Namespaces in use: `general`, `login`, `register`, `main-menu`,
|
||||
`settings`, `windows`, `campaigns`, `link`, `foundry`, `discord`.
|
||||
`settings`, `windows`, `campaigns`, `link`, `foundry`, `discord`, `docs`. (The `/docs` *content* is
|
||||
markdown under `app/content/docs` and is written in English; only its chrome — sidebar labels, prev /
|
||||
next — is translated.)
|
||||
|
||||
## 6. Conventions
|
||||
|
||||
@@ -216,6 +229,7 @@ new string to all three locales.** Namespaces in use: `general`, `login`, `regis
|
||||
- **New widget**: component in `components/viewer/widgets/{inline,display}/` + `widget_map` entry in `Marker.js`.
|
||||
- **New palette action**: `register({id, label, description, execute, isActive?})` from `~/services/ActionRegistry` (palette: `Ctrl/Cmd+K` or `/`).
|
||||
- **New theme color**: key in *both* `dark` and `light` maps in `colors.scss`, then `var(--color-<key>)`.
|
||||
- **New documentation page**: `app/content/docs/<group>/NN-name.md` whose first heading is its title (§5.1); a brand-new group also needs `groups.<folder>` in `i18n/locales/*/docs.json` (all three locales).
|
||||
|
||||
## 8. Known landmines (verified in code — do not "fix" silently, never make them worse)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user