Implement documentation #79
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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.
I'll start by exploring the repository structure to understand the codebase.
Now I have a clear picture. Let me write the docs services first.
Found it — a
*/sequence inside a block comment (i18n/locales/*/docs.json) terminated the comment early.Now the tests:
Everything is implemented and verified. Final summary:
What I did
/docsis 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/docsand/docs/<slug>.app.vuemoved, unchanged, intofrontend/app/components/views/AppShell.vue;app.vuenow holds only the site-wide head, the theme and<NuxtPage>.frontend/app/components/windows/MainMenuWindow.vuegained a Documentation link (label added tomain-menu.jsonin 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:@rolldice widget with its full expression syntax), Characters and items, Maps, pins and tokensThe Discord page lists every command the bot declares (table of
/characters,/character, and all seven/dragonrollsubcommands: 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.jsglobs the markdown, builds the sidebar (groups + pages + prev/next) and renders a page withmarked, giving every heading the anchor the sidebar links to.frontend/app/services/DocsMarkdown.jsholds the heading/slug helpers with no imports at all so the dependency-free test suite can load it.views/DocsView.vuedraws the contents sidebar, the article, and an "on this page" list of the current page's sections (responsive;docs.jsonchrome 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.mdupdated: §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
.mdfiles underapp/content/docsthat 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.Implementation is ready for review: #81