Implement documentation #79

Closed
opened 2026-10-15 17:11:23 +00:00 by Syndria98 · 6 comments
Owner

Add a documentation to dragonroll. Make it available under the /docs page.

Make a sidebar with contents, and also make it editable with markdown. Maybe you have to use nuxt pages for this.

Make that there are sections for the discord, foundry, and obsidian integration. For discord for example, list what the commands do.

Add a documentation to dragonroll. Make it available under the /docs page. Make a sidebar with contents, and also make it editable with markdown. Maybe you have to use nuxt pages for this. Make that there are sections for the discord, foundry, and obsidian integration. For discord for example, list what the commands do.
Syndria98 added the ai-ready label 2026-10-15 17:11:23 +00:00
Agent added the working label 2026-10-15 18:16:48 +00:00
Collaborator

I'll start by exploring the repository structure to understand the codebase.

I'll start by exploring the repository structure to understand the codebase.
Collaborator

Now I have a clear picture. Let me write the docs services first.

Now I have a clear picture. Let me write the docs services first.
Collaborator

Found it — a */ sequence inside a block comment (i18n/locales/*/docs.json) terminated the comment early.

Found it — a `*/` sequence inside a block comment (`i18n/locales/*/docs.json`) terminated the comment early.
Collaborator

Now the tests:

Now the tests:
Collaborator

Everything is implemented and verified. Final summary:

What I did

/docs is now a Nuxt-routed documentation site whose content is markdown files.

Routing (the app is now a two-page Nuxt app)

  • frontend/app/pages/index.vue + frontend/app/pages/[...all].vue — both render the window app, so every existing address (/, /link/authorize, the legacy /discord/authorize) behaves exactly as before.
  • frontend/app/pages/docs/index.vue + frontend/app/pages/docs/[slug].vue — render the documentation at /docs and /docs/<slug>.
  • The old shell of app.vue moved, unchanged, into frontend/app/components/views/AppShell.vue; app.vue now holds only the site-wide head, the theme and <NuxtPage>.
  • frontend/app/components/windows/MainMenuWindow.vue gained a Documentation link (label added to main-menu.json in all three locales).

Content: add a file, get a page

frontend/app/content/docs/<group>/<NN>-<page>.md — the folder is the sidebar group (its number orders groups), the file's number orders pages, the rest is the slug, and the first heading is the title. Pages written:

  • Getting started: What is Dragonroll?, Your first campaign
  • Using Dragonroll: Notes and markdown (folders, folding headings, the @roll dice widget with its full expression syntax), Characters and items, Maps, pins and tokens
  • Integrations: Connecting a service, Discord, Foundry VTT, Obsidian

The Discord page lists every command the bot declares (table of /characters, /character, and all seven /dragonroll subcommands: who can run it and what it does), plus assign rules and a troubleshooting table. The Foundry page covers pairing, auto-sync vs Force Sync, what syncs and what does not, and the optional bridge; the Obsidian page covers install, sign-in, both palette commands, the frontmatter identity and the conflict protection.

Sidebar / rendering

frontend/app/services/Docs.js globs the markdown, builds the sidebar (groups + pages + prev/next) and renders a page with marked, giving every heading the anchor the sidebar links to. frontend/app/services/DocsMarkdown.js holds the heading/slug helpers with no imports at all so the dependency-free test suite can load it. views/DocsView.vue draws the contents sidebar, the article, and an "on this page" list of the current page's sections (responsive; docs.json chrome strings in en/es/ca).

Tests — tests/docs.test.js, 17 tests, all passing (npm test: 282 pass / 0 fail)

Page well-formedness (title, unique slugs, numbered groups, group labels present in all three locales, no link pointing at an unpublished page), anchor consistency between markdown and rendered HTML, the Discord page documenting every slash command read out of discord-bot/src/commands.js, the Obsidian page documenting the plugin's registered commands, and the route wiring (docs routes render DocsView, catch-all renders AppShell, service-link screen still reachable).

Also

AGENTS.md updated: §5.1 no longer claims there are no pages (it describes the two pages and the docs file layout), plus the services list, i18n namespaces, recipes and the test line.

Verified with a real pnpm build + preview server: /, /some/deep/path → app shell; /docs, /docs/discord, /docs/foundry, /docs/obsidian, /docs/nope (not-found block) → documentation; /link/authorize → service link screen.

One note on interpretation: "editable with markdown" is implemented as docs-authored-in-markdown — the content is plain .md files under app/content/docs that the page renders, so editing a page means editing its markdown (no in-browser editor, which would need a new backend resource and permissions rules). Say the word if you wanted the browser-editable variant and I'll add it.

Everything is implemented and verified. Final summary: ## What I did **`/docs` is now a Nuxt-routed documentation site whose content is markdown files.** ### Routing (the app is now a two-page Nuxt app) - `frontend/app/pages/index.vue` + `frontend/app/pages/[...all].vue` — both render the window app, so every existing address (`/`, `/link/authorize`, the legacy `/discord/authorize`) behaves exactly as before. - `frontend/app/pages/docs/index.vue` + `frontend/app/pages/docs/[slug].vue` — render the documentation at `/docs` and `/docs/<slug>`. - The old shell of `app.vue` moved, unchanged, into `frontend/app/components/views/AppShell.vue`; `app.vue` now holds only the site-wide head, the theme and `<NuxtPage>`. - `frontend/app/components/windows/MainMenuWindow.vue` gained a **Documentation** link (label added to `main-menu.json` in all three locales). ### Content: add a file, get a page `frontend/app/content/docs/<group>/<NN>-<page>.md` — the folder is the sidebar group (its number orders groups), the file's number orders pages, the rest is the slug, and the first heading is the title. Pages written: - **Getting started**: *What is Dragonroll?*, *Your first campaign* - **Using Dragonroll**: *Notes and markdown* (folders, folding headings, the `@roll` dice widget with its full expression syntax), *Characters and items*, *Maps, pins and tokens* - **Integrations**: *Connecting a service*, *Discord*, *Foundry VTT*, *Obsidian* The Discord page lists **every command the bot declares** (table of `/characters`, `/character`, and all seven `/dragonroll` subcommands: who can run it and what it does), plus assign rules and a troubleshooting table. The Foundry page covers pairing, auto-sync vs *Force Sync*, what syncs and what does not, and the optional bridge; the Obsidian page covers install, sign-in, both palette commands, the frontmatter identity and the conflict protection. ### Sidebar / rendering `frontend/app/services/Docs.js` globs the markdown, builds the sidebar (groups + pages + prev/next) and renders a page with `marked`, giving every heading the anchor the sidebar links to. `frontend/app/services/DocsMarkdown.js` holds the heading/slug helpers with **no imports at all** so the dependency-free test suite can load it. `views/DocsView.vue` draws the contents sidebar, the article, and an "on this page" list of the current page's sections (responsive; `docs.json` chrome strings in en/es/ca). ### Tests — `tests/docs.test.js`, 17 tests, all passing (`npm test`: 282 pass / 0 fail) Page well-formedness (title, unique slugs, numbered groups, group labels present in all three locales, no link pointing at an unpublished page), anchor consistency between markdown and rendered HTML, the Discord page documenting every slash command read out of `discord-bot/src/commands.js`, the Obsidian page documenting the plugin's registered commands, and the route wiring (docs routes render DocsView, catch-all renders AppShell, service-link screen still reachable). ### Also `AGENTS.md` updated: §5.1 no longer claims there are no pages (it describes the two pages and the docs file layout), plus the services list, i18n namespaces, recipes and the test line. Verified with a real `pnpm build` + preview server: `/`, `/some/deep/path` → app shell; `/docs`, `/docs/discord`, `/docs/foundry`, `/docs/obsidian`, `/docs/nope` (not-found block) → documentation; `/link/authorize` → service link screen. One note on interpretation: **"editable with markdown" is implemented as docs-authored-in-markdown** — the content is plain `.md` files under `app/content/docs` that the page renders, so editing a page means editing its markdown (no in-browser editor, which would need a new backend resource and permissions rules). Say the word if you wanted the browser-editable variant and I'll add it.
Collaborator

Implementation is ready for review: #81

Implementation is ready for review: https://git.aranroig.com/Syndria98/dragonroll/pulls/81
Agent added help wanted and removed working labels 2026-10-15 19:07:10 +00:00
Sign in to join this conversation.
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Syndria98/dragonroll#79