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).
|
items, maps, dice widgets, sounds).
|
||||||
|
|
||||||
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth, CommonJS, entry `src/index.js`.
|
- `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.
|
- `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.
|
- `dragonroll-foundry/` — Foundry VTT module (`scripts/api.js`) + optional read-only snapshot bridge.
|
||||||
- `obsidian-plugin/` — plain JavaScript Obsidian plugin that imports/pushes campaign notes.
|
- `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
|
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`,
|
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. 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`,
|
`app/pages/` routes the only two things the frontend is. `index.vue` and the `[...all].vue` catch-all
|
||||||
`Tooltip`, `ContextMenu`) and boots: `GetUser()` (JWT in localStorage) → `RestoreCampaign()` or open
|
both render `components/views/AppShell.vue` — the window app, which has no routes of its own — and
|
||||||
`main_menu`; no user → `HasAdmin() ? 'login' : 'register' {firstTime:true}`. The one real URL is
|
`docs/index.vue` + `docs/[slug].vue` render `views/DocsView.vue`, the documentation at `/docs`.
|
||||||
`/link/authorize` (and the legacy `/discord/authorize`), which renders the service link screen instead
|
`app.vue` holds only what is site-wide (the head, the theme) and `<NuxtPage>`. AppShell boots:
|
||||||
of the app.
|
`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
|
Two kinds of screens: **windows** (floating draggable/resizable overlays) and **content** — the
|
||||||
campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`), turned on when
|
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
|
(`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:
|
`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`,
|
`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
|
### 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`
|
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
|
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`,
|
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
|
## 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 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 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 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)
|
## 8. Known landmines (verified in code — do not "fix" silently, never make them worse)
|
||||||
|
|
||||||
|
|||||||
@@ -1,43 +1,6 @@
|
|||||||
<script setup lang="ts">
|
<script setup lang="ts">
|
||||||
import ContentManager from './components/managers/ContentManager.vue';
|
// El que es veu és la pàgina que toca (app/pages): /docs porta la documentació, i la
|
||||||
import ToastManager from './components/managers/ToastManager.vue';
|
// resta de rutes obren l'aplicació de finestres. Aquí només hi ha el que és de tot el lloc.
|
||||||
import WindowManager from './components/managers/WindowManager.vue';
|
|
||||||
import ServiceLinkAuthorize from './components/views/ServiceLinkAuthorize.vue';
|
|
||||||
|
|
||||||
import { CreateWindow } from '@/services/Windows'
|
|
||||||
import { GetUser, HasAdmin } from './services/User';
|
|
||||||
import TooltipManager from './components/managers/TooltipManager.vue';
|
|
||||||
import ContextMenuManager from './components/managers/ContextMenuManager.vue';
|
|
||||||
import { useCampaignService } from './services/Campaign';
|
|
||||||
|
|
||||||
const { RestoreCampaign } = useCampaignService();
|
|
||||||
|
|
||||||
// Els serveis (Discord, Foundry, Obsidian) enllacen amb aquesta pantalla única; no són part
|
|
||||||
// de l'aplicació i no han d'arrencar les finestres normals. La ruta antiga de Discord també
|
|
||||||
// hi porta, perquè els enllaços que ja corren per Discord no queden morts.
|
|
||||||
const requestUrl = useRequestURL();
|
|
||||||
const isServiceLink = computed(() => {
|
|
||||||
const path = requestUrl.pathname.replace(/\/+$/, '');
|
|
||||||
return path === '/link/authorize' || path === '/discord/authorize';
|
|
||||||
});
|
|
||||||
|
|
||||||
async function start(){
|
|
||||||
if(GetUser()){
|
|
||||||
const restoredCampaign = await RestoreCampaign();
|
|
||||||
if (!restoredCampaign) {
|
|
||||||
CreateWindow('main_menu');
|
|
||||||
}
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
if(await HasAdmin()){
|
|
||||||
CreateWindow('login');
|
|
||||||
} else {
|
|
||||||
CreateWindow('register', {firstTime: true});
|
|
||||||
}
|
|
||||||
// DisplayToast('aqua', 'All plugins loaded successfully');
|
|
||||||
}
|
|
||||||
|
|
||||||
useHead({
|
useHead({
|
||||||
title: 'Dragonroll',
|
title: 'Dragonroll',
|
||||||
meta: [
|
meta: [
|
||||||
@@ -50,29 +13,9 @@ useHead({
|
|||||||
onMounted(() => {
|
onMounted(() => {
|
||||||
setupTheme();
|
setupTheme();
|
||||||
setTheme('dark');
|
setTheme('dark');
|
||||||
if(!isServiceLink.value){
|
|
||||||
start();
|
|
||||||
}
|
|
||||||
})
|
})
|
||||||
</script>
|
</script>
|
||||||
|
|
||||||
<template>
|
<template>
|
||||||
<ServiceLinkAuthorize v-if="isServiceLink"></ServiceLinkAuthorize>
|
<NuxtPage></NuxtPage>
|
||||||
<div v-else class="viewer">
|
|
||||||
<ToastManager></ToastManager>
|
|
||||||
<TooltipManager></TooltipManager>
|
|
||||||
<ContextMenuManager></ContextMenuManager>
|
|
||||||
<WindowManager></WindowManager>
|
|
||||||
<ContentManager></ContentManager>
|
|
||||||
<!-- Managers -->
|
|
||||||
</div>
|
|
||||||
</template>
|
</template>
|
||||||
|
|
||||||
<style scoped>
|
|
||||||
.viewer {
|
|
||||||
display: flex;
|
|
||||||
flex-direction: column;
|
|
||||||
width: 100%;
|
|
||||||
height: 100vh;
|
|
||||||
}
|
|
||||||
</style>
|
|
||||||
|
|||||||
67
frontend/app/components/views/AppShell.vue
Normal file
67
frontend/app/components/views/AppShell.vue
Normal file
@@ -0,0 +1,67 @@
|
|||||||
|
<script setup>
|
||||||
|
import ContentManager from '../managers/ContentManager.vue';
|
||||||
|
import ToastManager from '../managers/ToastManager.vue';
|
||||||
|
import WindowManager from '../managers/WindowManager.vue';
|
||||||
|
import ServiceLinkAuthorize from './ServiceLinkAuthorize.vue';
|
||||||
|
|
||||||
|
import { CreateWindow } from '@/services/Windows'
|
||||||
|
import { GetUser, HasAdmin } from '@/services/User';
|
||||||
|
import TooltipManager from '../managers/TooltipManager.vue';
|
||||||
|
import ContextMenuManager from '../managers/ContextMenuManager.vue';
|
||||||
|
import { useCampaignService } from '@/services/Campaign';
|
||||||
|
|
||||||
|
const { RestoreCampaign } = useCampaignService();
|
||||||
|
|
||||||
|
// Els serveis (Discord, Foundry, Obsidian) enllacen amb aquesta pantalla única; no són part
|
||||||
|
// de l'aplicació i no han d'arrencar les finestres normals. La ruta antiga de Discord també
|
||||||
|
// hi porta, perquè els enllaços que ja corren per Discord no queden morts.
|
||||||
|
const requestUrl = useRequestURL();
|
||||||
|
const isServiceLink = computed(() => {
|
||||||
|
const path = requestUrl.pathname.replace(/\/+$/, '');
|
||||||
|
return path === '/link/authorize' || path === '/discord/authorize';
|
||||||
|
});
|
||||||
|
|
||||||
|
async function start(){
|
||||||
|
if(GetUser()){
|
||||||
|
const restoredCampaign = await RestoreCampaign();
|
||||||
|
if (!restoredCampaign) {
|
||||||
|
CreateWindow('main_menu');
|
||||||
|
}
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
if(await HasAdmin()){
|
||||||
|
CreateWindow('login');
|
||||||
|
} else {
|
||||||
|
CreateWindow('register', {firstTime: true});
|
||||||
|
}
|
||||||
|
// DisplayToast('aqua', 'All plugins loaded successfully');
|
||||||
|
}
|
||||||
|
|
||||||
|
onMounted(() => {
|
||||||
|
if(!isServiceLink.value){
|
||||||
|
start();
|
||||||
|
}
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<ServiceLinkAuthorize v-if="isServiceLink"></ServiceLinkAuthorize>
|
||||||
|
<div v-else class="viewer">
|
||||||
|
<ToastManager></ToastManager>
|
||||||
|
<TooltipManager></TooltipManager>
|
||||||
|
<ContextMenuManager></ContextMenuManager>
|
||||||
|
<WindowManager></WindowManager>
|
||||||
|
<ContentManager></ContentManager>
|
||||||
|
<!-- Managers -->
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<style scoped>
|
||||||
|
.viewer {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
width: 100%;
|
||||||
|
height: 100vh;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
404
frontend/app/components/views/DocsView.vue
Normal file
404
frontend/app/components/views/DocsView.vue
Normal file
@@ -0,0 +1,404 @@
|
|||||||
|
<script setup>
|
||||||
|
import { computed } from 'vue';
|
||||||
|
import { GetDocsFirstSlug, GetDocsNav, GetDocsPage } from '~/services/Docs';
|
||||||
|
|
||||||
|
// La documentació pública, a /docs: el sumari a l'esquerra, la pàgina al centre i els
|
||||||
|
// apartats d'aquesta pàgina a la dreta. Tot el que hi ha escrit ve dels markdown de
|
||||||
|
// app/content/docs (mira ~/services/Docs.js), i cada enllaç del sumari és una ruta,
|
||||||
|
// així que moure-s'hi no recarrega la pàgina.
|
||||||
|
const route = useRoute();
|
||||||
|
|
||||||
|
const slug = computed(() => String(route.params.slug || GetDocsFirstSlug()));
|
||||||
|
const page = computed(() => GetDocsPage(slug.value));
|
||||||
|
const nav = GetDocsNav();
|
||||||
|
|
||||||
|
useHead({
|
||||||
|
title: computed(() => `${page.value?.title || 'Documentation'} · Dragonroll`)
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<div class="docs">
|
||||||
|
<aside class="docs-sidebar">
|
||||||
|
<NuxtLink class="docs-brand" to="/">
|
||||||
|
<img src="/img/logo.png" alt="Dragonroll logo" class="docs-logo" draggable="false">
|
||||||
|
<span>{{ $t('docs.title') }}</span>
|
||||||
|
</NuxtLink>
|
||||||
|
|
||||||
|
<nav class="docs-contents" :aria-label="$t('docs.contents')">
|
||||||
|
<section v-for="group in nav" :key="group.key" class="docs-group">
|
||||||
|
<h2 class="docs-group-title">{{ $t(`docs.groups.${group.key}`) }}</h2>
|
||||||
|
<ul>
|
||||||
|
<li v-for="entry in group.pages" :key="entry.slug">
|
||||||
|
<NuxtLink
|
||||||
|
:to="entry.href"
|
||||||
|
class="docs-nav-link"
|
||||||
|
:class="{ active: entry.slug === slug }"
|
||||||
|
>{{ entry.title }}</NuxtLink>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
</nav>
|
||||||
|
|
||||||
|
<NuxtLink class="docs-open" to="/">{{ $t('docs.open-app') }}</NuxtLink>
|
||||||
|
</aside>
|
||||||
|
|
||||||
|
<main class="docs-main">
|
||||||
|
<template v-if="page">
|
||||||
|
<article class="docs-article">
|
||||||
|
<p class="docs-kicker">{{ $t(`docs.groups.${page.group}`) }}</p>
|
||||||
|
<!-- El contingut és markdown nostre, de app/content/docs -->
|
||||||
|
<div class="docs-markdown" v-html="page.html"></div>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
<nav class="docs-pager">
|
||||||
|
<NuxtLink
|
||||||
|
v-if="page.previous"
|
||||||
|
:to="page.previous.href"
|
||||||
|
class="docs-pager-link"
|
||||||
|
>
|
||||||
|
<span class="docs-pager-label">{{ $t('docs.previous') }}</span>
|
||||||
|
<strong>{{ page.previous.title }}</strong>
|
||||||
|
</NuxtLink>
|
||||||
|
<NuxtLink
|
||||||
|
v-if="page.next"
|
||||||
|
:to="page.next.href"
|
||||||
|
class="docs-pager-link next"
|
||||||
|
>
|
||||||
|
<span class="docs-pager-label">{{ $t('docs.next') }}</span>
|
||||||
|
<strong>{{ page.next.title }}</strong>
|
||||||
|
</NuxtLink>
|
||||||
|
</nav>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<article v-else class="docs-article">
|
||||||
|
<h1>{{ $t('docs.title') }}</h1>
|
||||||
|
<p>{{ $t('docs.not-found', { page: slug }) }}</p>
|
||||||
|
<p><NuxtLink to="/docs">{{ $t('docs.back-to-docs') }}</NuxtLink></p>
|
||||||
|
</article>
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<aside
|
||||||
|
v-if="page && page.headings.length"
|
||||||
|
class="docs-sections"
|
||||||
|
:aria-label="$t('docs.on-this-page')"
|
||||||
|
>
|
||||||
|
<h2>{{ $t('docs.on-this-page') }}</h2>
|
||||||
|
<ul>
|
||||||
|
<li
|
||||||
|
v-for="heading in page.headings"
|
||||||
|
:key="heading.slug"
|
||||||
|
:class="`depth-${heading.depth}`"
|
||||||
|
>
|
||||||
|
<a :href="`#${heading.slug}`">{{ heading.text }}</a>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</aside>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<style scoped lang="scss">
|
||||||
|
.docs {
|
||||||
|
display: flex;
|
||||||
|
align-items: flex-start;
|
||||||
|
width: 100%;
|
||||||
|
min-height: 100vh;
|
||||||
|
box-sizing: border-box;
|
||||||
|
background-color: var(--color-background);
|
||||||
|
color: var(--color-text);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sidebar,
|
||||||
|
.docs-sections {
|
||||||
|
position: sticky;
|
||||||
|
top: 0;
|
||||||
|
max-height: 100vh;
|
||||||
|
overflow-y: auto;
|
||||||
|
box-sizing: border-box;
|
||||||
|
padding: 18px 14px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sidebar {
|
||||||
|
flex: 0 0 268px;
|
||||||
|
width: 268px;
|
||||||
|
border-right: 1px solid var(--color-border);
|
||||||
|
background-color: var(--color-background-light);
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 14px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-brand {
|
||||||
|
display: flex;
|
||||||
|
align-items: center;
|
||||||
|
gap: 10px;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 1.15rem;
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-logo {
|
||||||
|
width: 30px;
|
||||||
|
height: 30px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-contents {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-group-title {
|
||||||
|
margin: 0 0 6px 0;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 0.78rem;
|
||||||
|
font-weight: normal;
|
||||||
|
letter-spacing: 0.08em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-contents ul {
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
list-style: none;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 2px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-nav-link {
|
||||||
|
display: block;
|
||||||
|
padding: 6px 9px;
|
||||||
|
border-radius: 6px;
|
||||||
|
font-size: 0.97rem;
|
||||||
|
line-height: 1.35;
|
||||||
|
color: var(--color-text);
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-nav-link:hover {
|
||||||
|
background-color: var(--color-hover);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-nav-link.active {
|
||||||
|
background-color: var(--color-background-soft);
|
||||||
|
color: var(--color-link);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-open {
|
||||||
|
margin-top: auto;
|
||||||
|
padding: 8px 9px;
|
||||||
|
border: 1px solid var(--color-border);
|
||||||
|
border-radius: 6px;
|
||||||
|
background-color: var(--color-button-background);
|
||||||
|
font-size: 0.95rem;
|
||||||
|
text-align: center;
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-open:hover {
|
||||||
|
background-color: var(--color-button-hover);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-main {
|
||||||
|
flex: 1;
|
||||||
|
min-width: 0;
|
||||||
|
padding: 26px 34px 60px 34px;
|
||||||
|
box-sizing: border-box;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-article {
|
||||||
|
max-width: 760px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-kicker {
|
||||||
|
margin: 0 0 4px 0;
|
||||||
|
font-size: 0.8rem;
|
||||||
|
letter-spacing: 0.08em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager {
|
||||||
|
max-width: 760px;
|
||||||
|
margin-top: 34px;
|
||||||
|
padding-top: 18px;
|
||||||
|
border-top: 1px solid var(--color-border);
|
||||||
|
display: flex;
|
||||||
|
gap: 14px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-link {
|
||||||
|
flex: 1 1 0;
|
||||||
|
min-width: 0;
|
||||||
|
padding: 10px 12px;
|
||||||
|
border: 1px solid var(--color-border);
|
||||||
|
border-radius: 8px;
|
||||||
|
color: var(--color-text);
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-link:hover {
|
||||||
|
background-color: var(--color-hover);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-link.next {
|
||||||
|
text-align: right;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-label {
|
||||||
|
display: block;
|
||||||
|
font-size: 0.78rem;
|
||||||
|
letter-spacing: 0.06em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections {
|
||||||
|
flex: 0 0 220px;
|
||||||
|
width: 220px;
|
||||||
|
border-left: 1px solid var(--color-border);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections h2 {
|
||||||
|
margin: 0 0 8px 0;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 0.78rem;
|
||||||
|
font-weight: normal;
|
||||||
|
letter-spacing: 0.08em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections ul {
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
list-style: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections li.depth-3 {
|
||||||
|
padding-left: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections a {
|
||||||
|
display: block;
|
||||||
|
padding: 3px 0;
|
||||||
|
font-size: 0.9rem;
|
||||||
|
line-height: 1.35;
|
||||||
|
color: var(--color-gray);
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sections a:hover {
|
||||||
|
color: var(--color-link);
|
||||||
|
}
|
||||||
|
|
||||||
|
/* El markdown renderitzat: tot dins de .docs-markdown, perquè ve de v-html. */
|
||||||
|
.docs-markdown :deep(h1) {
|
||||||
|
margin: 0 0 14px 0;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 2rem;
|
||||||
|
font-weight: normal;
|
||||||
|
line-height: 1.2;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(h2) {
|
||||||
|
margin: 30px 0 10px 0;
|
||||||
|
padding-bottom: 4px;
|
||||||
|
border-bottom: 1px solid var(--color-border);
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 1.35rem;
|
||||||
|
font-weight: normal;
|
||||||
|
scroll-margin-top: 20px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(h3) {
|
||||||
|
margin: 22px 0 8px 0;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 1.1rem;
|
||||||
|
font-weight: normal;
|
||||||
|
scroll-margin-top: 20px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(p),
|
||||||
|
.docs-markdown :deep(li) {
|
||||||
|
line-height: 1.65;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(ul),
|
||||||
|
.docs-markdown :deep(ol) {
|
||||||
|
margin: 10px 0;
|
||||||
|
padding-left: 1.5em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(a) {
|
||||||
|
color: var(--color-link);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(code) {
|
||||||
|
padding: 1px 5px;
|
||||||
|
border-radius: 4px;
|
||||||
|
background-color: var(--color-background-light);
|
||||||
|
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
||||||
|
font-size: 0.9em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(pre) {
|
||||||
|
margin: 14px 0;
|
||||||
|
padding: 12px 14px;
|
||||||
|
border: 1px solid var(--color-border);
|
||||||
|
border-radius: 8px;
|
||||||
|
background-color: var(--color-background-light);
|
||||||
|
overflow-x: auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(pre code) {
|
||||||
|
padding: 0;
|
||||||
|
background-color: transparent;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(table) {
|
||||||
|
margin: 14px 0;
|
||||||
|
border-collapse: collapse;
|
||||||
|
width: 100%;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(th),
|
||||||
|
.docs-markdown :deep(td) {
|
||||||
|
padding: 7px 10px;
|
||||||
|
border: 1px solid var(--color-border);
|
||||||
|
text-align: left;
|
||||||
|
vertical-align: top;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-markdown :deep(th) {
|
||||||
|
background-color: var(--color-background-light);
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (max-width: 1200px) {
|
||||||
|
.docs-sections {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (max-width: 900px) {
|
||||||
|
.docs {
|
||||||
|
flex-direction: column;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-sidebar,
|
||||||
|
.docs-sections {
|
||||||
|
position: static;
|
||||||
|
max-height: none;
|
||||||
|
width: 100%;
|
||||||
|
border-left: none;
|
||||||
|
border-right: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-main {
|
||||||
|
padding: 20px 18px 40px 18px;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</style>
|
||||||
@@ -76,6 +76,7 @@ onMounted(() => {
|
|||||||
<div class="vert bot">
|
<div class="vert bot">
|
||||||
<div class="button-container">
|
<div class="button-container">
|
||||||
<button class="btn-primary button-expand sound-click" v-on:click="CreateCampaignWindow" ref="campaignButton">{{ $t("main-menu.create-campaign") }}</button>
|
<button class="btn-primary button-expand sound-click" v-on:click="CreateCampaignWindow" ref="campaignButton">{{ $t("main-menu.create-campaign") }}</button>
|
||||||
|
<a class="btn-primary button-expand docs-link" href="/docs">{{ $t("main-menu.documentation") }}</a>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
@@ -145,6 +146,24 @@ h2, h3 {
|
|||||||
flex-direction: column;
|
flex-direction: column;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* L'enllaç a la documentació és un `<a>` i els botons estan estilats per element, així
|
||||||
|
que li toca portar el mateix look. */
|
||||||
|
.docs-link {
|
||||||
|
display: block;
|
||||||
|
padding: 14px;
|
||||||
|
border-radius: 6px;
|
||||||
|
border: solid 1px var(--color-border);
|
||||||
|
background-color: var(--color-button-background);
|
||||||
|
color: var(--color-text);
|
||||||
|
text-align: center;
|
||||||
|
text-decoration: none;
|
||||||
|
transition: 300ms background-color;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-link:hover {
|
||||||
|
background-color: var(--color-button-hover);
|
||||||
|
}
|
||||||
|
|
||||||
p {
|
p {
|
||||||
user-select: none;
|
user-select: none;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,45 @@
|
|||||||
|
# What is Dragonroll?
|
||||||
|
|
||||||
|
Dragonroll is a free and open-source helper for tabletop RPG campaigns. It keeps the things a group
|
||||||
|
carries around a table in one place — the campaign's notes, its characters, its items, its maps — and
|
||||||
|
lets the tools you already play with read and change them: Discord, Foundry VTT and Obsidian.
|
||||||
|
|
||||||
|
It is not a full virtual tabletop. There is no game loop, no combat tracker and no rule engine:
|
||||||
|
Dragonroll is the shared memory of a campaign, and the place its characters and items are written
|
||||||
|
down.
|
||||||
|
|
||||||
|
## What you get
|
||||||
|
|
||||||
|
- **Campaigns.** Every note, character, item and map belongs to one campaign, and each campaign has
|
||||||
|
its own colour, description and integrations. [Start one](/docs/your-first-campaign).
|
||||||
|
- **Notes in markdown.** The campaign's text lives in markdown notes, filed into folders that nest as
|
||||||
|
deep as you need. Notes can hold a [dice widget](/docs/notes-and-markdown) that rolls when you
|
||||||
|
look at it.
|
||||||
|
- **Characters and items.** Actors (characters, NPCs and creatures) have a sheet with ability scores,
|
||||||
|
combat stats, proficiencies, traits, spells and an inventory. Items have a category, a rarity and an
|
||||||
|
icon. See [characters and items](/docs/characters-and-items).
|
||||||
|
- **Maps.** Upload a map image with a grid, then pin notes onto the places they belong and stand your
|
||||||
|
characters on the grid as [tokens](/docs/maps).
|
||||||
|
- **Integrations.** Consult the campaign from [Discord](/docs/discord), keep a Foundry VTT world and
|
||||||
|
a campaign [in step](/docs/foundry), and write campaign notes in [Obsidian](/docs/obsidian).
|
||||||
|
|
||||||
|
## How it is put together
|
||||||
|
|
||||||
|
Three pieces work together, and you only ever see the first of them:
|
||||||
|
|
||||||
|
| Piece | What it does |
|
||||||
|
| --- | --- |
|
||||||
|
| The web app | What you open: campaigns, notes, characters, items, maps, and the documentation you are reading |
|
||||||
|
| The API | Stores everything the app shows and answers the integrations' requests |
|
||||||
|
| The integrations | The Discord bot, the Foundry VTT module and the Obsidian plugin |
|
||||||
|
|
||||||
|
You sign in to the app with one account, and everything you create belongs to you. Integrations never
|
||||||
|
hold a Dragonroll login: they ask you to authorize them for one campaign, which
|
||||||
|
[you can take back](/docs/connecting-a-service) at any time.
|
||||||
|
|
||||||
|
## Where to go next
|
||||||
|
|
||||||
|
- New here? [Create your first campaign](/docs/your-first-campaign).
|
||||||
|
- Writing the campaign down? [Notes and markdown](/docs/notes-and-markdown).
|
||||||
|
- Playing on a screen? [Maps, pins and tokens](/docs/maps).
|
||||||
|
- Connecting the tools you use? [Connecting a service](/docs/connecting-a-service).
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
# Your first campaign
|
||||||
|
|
||||||
|
## Signing in
|
||||||
|
|
||||||
|
The very first time you open a Dragonroll server there is no account yet, so the app asks you to
|
||||||
|
create one: that first account becomes the server's **administrator**, which is the account that can
|
||||||
|
later create or remove the other accounts. Everyone else is invited to register by whoever runs the
|
||||||
|
server.
|
||||||
|
|
||||||
|
Sign in with your username or your email and your password. Sessions last 48 hours, after which the
|
||||||
|
app asks you again. Under your name in the main menu you can change your profile — your name, your
|
||||||
|
email and the avatar that shows up beside your characters.
|
||||||
|
|
||||||
|
## The main menu
|
||||||
|
|
||||||
|
The main menu is where you pick up where you left off:
|
||||||
|
|
||||||
|
- your campaigns, ready to open,
|
||||||
|
- **Create campaign** to add one,
|
||||||
|
- **Settings**, with your own appearance and language, and an *Administration* tab for
|
||||||
|
administrators to manage the other accounts,
|
||||||
|
- **Log out**.
|
||||||
|
|
||||||
|
## Creating a campaign
|
||||||
|
|
||||||
|
**Create campaign** asks for three things: a name, a short description and an accent colour. The
|
||||||
|
colour follows the campaign wherever it shows up, so a group that runs two campaigns can tell them
|
||||||
|
apart at a glance. Nothing else about a campaign is fixed: you can change the name, description and
|
||||||
|
colour later in its settings.
|
||||||
|
|
||||||
|
## The campaign workspace
|
||||||
|
|
||||||
|
Opening a campaign replaces the menu with its workspace.
|
||||||
|
|
||||||
|
| Part | What it holds |
|
||||||
|
| --- | --- |
|
||||||
|
| Top bar | The campaign's name, the search, **Settings** and **Exit** |
|
||||||
|
| Sidebar | The campaign's contents, in four sections: **Notes**, **Actors & Characters**, **Items** and **Maps** |
|
||||||
|
| Note column | The notes you have open, side by side, or the map you have anchored |
|
||||||
|
| Status bar | What the app is doing: saving, syncing, and errors when something fails |
|
||||||
|
|
||||||
|
The sidebar is the heart of it. Each of its sections lists the entries of that kind, and each entry
|
||||||
|
can stand in a folder: folders nest, so a campaign can be organised however the group thinks of it.
|
||||||
|
The sidebar itself collapses to give the notes room when you are showing a screen at the table.
|
||||||
|
|
||||||
|
## Finding things
|
||||||
|
|
||||||
|
The search in the top bar looks through the notes, characters, items and maps of the campaign you are
|
||||||
|
in, and opens whatever you pick from the results. **Cmd+K** (or **Ctrl+K**) puts the cursor in it.
|
||||||
|
|
||||||
|
## Campaign settings
|
||||||
|
|
||||||
|
**Settings** in the top bar has two tabs:
|
||||||
|
|
||||||
|
- **Basic** — the campaign's name and colour.
|
||||||
|
- **Integrations** — which external services are connected to this campaign and how to
|
||||||
|
[connect one](/docs/connecting-a-service), plus the address of the Foundry VTT instance when the
|
||||||
|
campaign reads icons from a linked world.
|
||||||
|
|
||||||
|
**Exit** leaves the campaign and returns to the main menu. Nothing is lost: the notes you had open and
|
||||||
|
the campaign you were in are remembered for the next time you open the app.
|
||||||
|
|
||||||
|
## Next
|
||||||
|
|
||||||
|
- Write the campaign down in [notes and markdown](/docs/notes-and-markdown).
|
||||||
|
- Write its characters and items on [sheets](/docs/characters-and-items).
|
||||||
|
- Put it on a [map](/docs/maps).
|
||||||
@@ -0,0 +1,89 @@
|
|||||||
|
# Notes and markdown
|
||||||
|
|
||||||
|
Notes are where a campaign is written down: sessions, NPCs, the lore of a city, the ritual the party
|
||||||
|
found in a dungeon. They are plain markdown, so anything you already know from README files and
|
||||||
|
Obsidian works as it is.
|
||||||
|
|
||||||
|
## Opening and editing a note
|
||||||
|
|
||||||
|
Clicking a note in the sidebar opens it in the note column, where you can have several open side by
|
||||||
|
side. A note opens in **display mode**, showing its formatted markdown. Press **Cmd+E** (**Ctrl+E**)
|
||||||
|
to edit its source, and **Cmd+S** (**Ctrl+S**) to save it; a dot in the note's title bar reminds you
|
||||||
|
that there is something to save. The cross in the title bar closes the note — it does not delete it.
|
||||||
|
|
||||||
|
## Folders
|
||||||
|
|
||||||
|
The sidebar's sections hold notes in folders, and folders hold folders, so a campaign can be nested as
|
||||||
|
deep as it needs. Right-clicking gives the commands:
|
||||||
|
|
||||||
|
| Right-click on… | You get |
|
||||||
|
| --- | --- |
|
||||||
|
| a note | Open, Rename, a colour, the folder to move it to, Delete |
|
||||||
|
| a folder | New note in it, Rename, a colour, Delete folder |
|
||||||
|
|
||||||
|
Dragging a note onto a folder moves it there, and dropping it at the bottom of the list takes it back
|
||||||
|
to the root. Colouring a note or a folder tints its row in the sidebar, which is a quick way to mark
|
||||||
|
what matters.
|
||||||
|
|
||||||
|
Deleting a folder does not delete your notes: the notes it held move up to its parent folder, its
|
||||||
|
sub-folders move up with them, and only the empty folders go away.
|
||||||
|
|
||||||
|
## Markdown
|
||||||
|
|
||||||
|
Headings, **bold**, *italic*, lists, quotes, tables, code and links all work:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## The Wreck of the Salt Gull
|
||||||
|
|
||||||
|
- [ ] Burn the manifest
|
||||||
|
- [x] Ask the harbourmaster
|
||||||
|
|
||||||
|
| Cargo | Worth |
|
||||||
|
| --- | --- |
|
||||||
|
| Salted fish | 20 gp |
|
||||||
|
```
|
||||||
|
|
||||||
|
Clicking a heading **folds** the section under it — handy when you are reading a long note on a
|
||||||
|
projector and only want the part you are talking about. Sub-headings fold with their parent.
|
||||||
|
|
||||||
|
## Rolling dice in a note
|
||||||
|
|
||||||
|
A note can hold a dice widget: a button that rolls and shows the result right there, so the book of a
|
||||||
|
spell does not need a second app next to it.
|
||||||
|
|
||||||
|
Write `@roll` and the expression in square brackets to drop it in the middle of a sentence:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
The goblin attacks with @roll[1d20+4].
|
||||||
|
```
|
||||||
|
|
||||||
|
Or in a block of its own, between `@roll` and `@end`, when the roll is worth showing on its own line:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
@roll
|
||||||
|
8d6
|
||||||
|
@end
|
||||||
|
```
|
||||||
|
|
||||||
|
Either way the widget shows the expression as a button: press it and the dice land, with every die and
|
||||||
|
the total spelled out. Press it again to roll again. Only the expression itself goes between `@roll`
|
||||||
|
and `@end` — write the note about the roll next to the widget, not inside it.
|
||||||
|
|
||||||
|
The expression understands:
|
||||||
|
|
||||||
|
| Written | Meaning |
|
||||||
|
| --- | --- |
|
||||||
|
| `d20`, `1d20` | one die; the number in front is how many, so `4d6` |
|
||||||
|
| `d20adv`, `d20dis` | roll twice and keep the higher / the lower |
|
||||||
|
| `4d6kh1`, `4d6kl1` | keep the highest / lowest one of four (any number after `kh` / `kl`) |
|
||||||
|
| `+`, `-`, `*`, `/` | arithmetic; `2d6+3`, `1d8/2` |
|
||||||
|
| `( )` | grouping, as in `(1d8+4)*2` |
|
||||||
|
| `-3` | a negative number |
|
||||||
|
|
||||||
|
Division rounds down, the way damage does. Spaces between the parts of an expression do not matter, but
|
||||||
|
a modifier belongs right after the dice: write `4d6kh1`, not `4d6 kh 1`.
|
||||||
|
|
||||||
|
## Next
|
||||||
|
|
||||||
|
- Put the people and things of your notes on [sheets](/docs/characters-and-items).
|
||||||
|
- Pin a note onto a spot on a [map](/docs/maps).
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
# Characters and items
|
||||||
|
|
||||||
|
The **Actors & Characters** and **Items** sections of the sidebar hold the people and things of a
|
||||||
|
campaign as entries of their own, with a sheet each. They can be written by hand, and they are also
|
||||||
|
what a linked [Foundry VTT](/docs/foundry) world keeps itself in step with.
|
||||||
|
|
||||||
|
## Actors
|
||||||
|
|
||||||
|
An actor is anyone the campaign can point at: a **Character**, an **NPC** or a **Creature**. Creating
|
||||||
|
one asks for the few fields that identify it — type, species, class, level, background, and a challenge
|
||||||
|
rating for the monsters — and the rest is filled in on its sheet.
|
||||||
|
|
||||||
|
Opening an actor opens its **character sheet**, in tabs:
|
||||||
|
|
||||||
|
| Tab | What it holds |
|
||||||
|
| --- | --- |
|
||||||
|
| Ability Scores | Strength, Dexterity, Constitution, Intelligence, Wisdom, Charisma, and the proficiency bonus |
|
||||||
|
| Inventory | What it carries: item, quantity and weight each, with the total carried weight added up |
|
||||||
|
| Traits | Features, traits and other details, as text |
|
||||||
|
| Spells | The spells it knows, one per line |
|
||||||
|
|
||||||
|
Combat lives above the tabs: armor class, speed, initiative, current and maximum hit points, and hit
|
||||||
|
dice. The photo at the top of the sheet is what shows up next to the character everywhere else —
|
||||||
|
including in [Discord](/docs/discord), where players can read the sheet of the character they hold.
|
||||||
|
|
||||||
|
**Edit** turns the sheet into fields you can change; **Save sheet** writes them back. Characters are
|
||||||
|
filed in folders like notes are, so a campaign can keep its party, its villains and its bestiary
|
||||||
|
apart.
|
||||||
|
|
||||||
|
## Items
|
||||||
|
|
||||||
|
An item is anything the campaign names: a weapon, a potion, a piece of treasure. Its sheet holds a
|
||||||
|
name, a description, a **category** (weapon, armor, shield, adventuring gear, magic item, consumable,
|
||||||
|
tool, treasure, other), a **rarity** from common to artifact, a weight in pounds, and its properties
|
||||||
|
("finesse, versatile").
|
||||||
|
|
||||||
|
The rarity colours the item's row in the sidebar — common white, uncommon green, rare blue, very rare
|
||||||
|
purple, legendary orange — so what is worth something stands out while you scroll.
|
||||||
|
|
||||||
|
Every item can have an icon. Upload an image, or pick one out of the icon library your linked Foundry
|
||||||
|
world ships with, browsing its folders one at a time.
|
||||||
|
|
||||||
|
## Characters on the table
|
||||||
|
|
||||||
|
Drag an actor out of the sidebar and drop it on a map and it stands there as a
|
||||||
|
[token](/docs/maps), sized to the map's grid. Drag a note instead and it is filed into whatever folder
|
||||||
|
you drop it on.
|
||||||
51
frontend/app/content/docs/02-using-dragonroll/03-maps.md
Normal file
51
frontend/app/content/docs/02-using-dragonroll/03-maps.md
Normal file
@@ -0,0 +1,51 @@
|
|||||||
|
# Maps, pins and tokens
|
||||||
|
|
||||||
|
A map is a picture of a place — a dungeon floor, a town, a combat encounter — with a grid laid over
|
||||||
|
it. On top of the picture you can pin the notes that belong to a spot and stand the campaign's
|
||||||
|
characters on its cells.
|
||||||
|
|
||||||
|
## Creating a map
|
||||||
|
|
||||||
|
**Maps → New map** asks for an image and the grid that goes with it:
|
||||||
|
|
||||||
|
| Setting | What it is |
|
||||||
|
| --- | --- |
|
||||||
|
| Map image | A photo or scan of the map. Uploading a new one replaces it, and leaving it empty keeps the current image |
|
||||||
|
| Grid size (px) | How wide one grid cell is in the image, in image pixels |
|
||||||
|
| Offset X / Offset Y | Where the grid starts in the image, so the grid can be lined up with the drawing |
|
||||||
|
| Scale | How much distance one cell stands for, like 5 feet |
|
||||||
|
|
||||||
|
The grid size, offsets and scale are what let the app turn a point on the screen into a cell of the
|
||||||
|
map, so a token stands where it should and pins stay put when you zoom.
|
||||||
|
|
||||||
|
## Looking at a map
|
||||||
|
|
||||||
|
Clicking a map in the sidebar anchors it in the place the open notes occupy, and **Open in window**
|
||||||
|
puts it in a window of its own, which you can drag next to the notes. Once a map is on screen:
|
||||||
|
|
||||||
|
- scroll to zoom towards the cursor, or use the zoom buttons and **Fit to window**,
|
||||||
|
- drag to pan,
|
||||||
|
- **Show grid** turns the grid overlay on and off. The grid is drawn over the image, so its lines stay
|
||||||
|
crisp whatever the zoom.
|
||||||
|
|
||||||
|
## Pinning notes
|
||||||
|
|
||||||
|
Right-click anywhere on a map and pick **Pin a note here**, then choose the note: a marker appears on
|
||||||
|
that spot, and clicking the marker opens the note. A pinned note can be read straight off the map
|
||||||
|
without hunting for it in the sidebar, which is what makes a town map usable at the table.
|
||||||
|
|
||||||
|
**Remove pin** takes the marker off; the note itself is untouched. Deleting a note that is pinned drops
|
||||||
|
its pins.
|
||||||
|
|
||||||
|
## Tokens
|
||||||
|
|
||||||
|
Drag an actor from the sidebar onto a map and it stands there as a token: it snaps to the centre of the
|
||||||
|
cell you dropped it on and is sized by that cell, so a huge creature can be given more than one cell by
|
||||||
|
sizing it up on the map's settings.
|
||||||
|
|
||||||
|
Once a token is on the map you can drag it to another cell, step it across the grid one cell at a time
|
||||||
|
with the **arrow keys**, and take it off with **Delete**. Clicking a token opens the sheet of the actor
|
||||||
|
it stands for.
|
||||||
|
|
||||||
|
Tokens belong to the map, not to the actor: the same character can stand on several maps, and taking a
|
||||||
|
token off does not remove the character from the campaign.
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
# Connecting a service
|
||||||
|
|
||||||
|
Dragonroll talks to three services: [Discord](/docs/discord), [Foundry VTT](/docs/foundry) and
|
||||||
|
[Obsidian](/docs/obsidian). They all connect the same way, and none of them is given your Dragonroll
|
||||||
|
password.
|
||||||
|
|
||||||
|
## How a connection works
|
||||||
|
|
||||||
|
A service asks Dragonroll for a **sign-up link** and shows it to you. You open that link in your
|
||||||
|
browser, sign in if you are not signed in already, and pick which of your campaigns the service may
|
||||||
|
use. Only then does the service get its own credential, which lets it read and change that one
|
||||||
|
campaign and nothing else.
|
||||||
|
|
||||||
|
| You see | What it means |
|
||||||
|
| --- | --- |
|
||||||
|
| A link in Discord, in the Foundry module or in the Obsidian plugin | The service is waiting for you to pick a campaign |
|
||||||
|
| A campaign picker in your browser | Sign in and choose the campaign, and the service is connected |
|
||||||
|
| "Connected" in the service | It picked up its credential and can start working |
|
||||||
|
|
||||||
|
The link is short-lived — it expires after ten minutes — and can only be used once. If you close it
|
||||||
|
without choosing, ask the service for a new one. If a service loses the credential it was given, it
|
||||||
|
asks for a new link too: nothing is kept that would let it back in.
|
||||||
|
|
||||||
|
## What a connection allows
|
||||||
|
|
||||||
|
What a service may do is decided by the campaign you pick, so check the name before you confirm. The
|
||||||
|
screen tells you which service is asking, and what it wants:
|
||||||
|
|
||||||
|
- a **Discord server** reads the campaign's characters, so whoever is in that server can read them,
|
||||||
|
- a **Foundry world** keeps its actors and items in step with the campaign, which means it writes into
|
||||||
|
it, and Dragonroll writes into it,
|
||||||
|
- **Obsidian** reads the campaign's notes and pushes the ones you tell it to.
|
||||||
|
|
||||||
|
A campaign holds one link per service: linking a second Foundry world, or a second Discord server,
|
||||||
|
replaces the one it had. Authorizing a service with a different Dragonroll account replaces who the
|
||||||
|
service answers to.
|
||||||
|
|
||||||
|
## Seeing and undoing a connection
|
||||||
|
|
||||||
|
Open the campaign and look at **Settings → Integrations**. It lists the three services and, for each
|
||||||
|
one, whether it is connected, what is connected to it, and which Dragonroll account authorized it.
|
||||||
|
|
||||||
|
**Unlink** ends it. The service loses access the next time it asks — nothing it already wrote into the
|
||||||
|
campaign is deleted, and nothing about your campaign changes. To use the service again, start a new
|
||||||
|
link from its own side.
|
||||||
|
|
||||||
|
## Next
|
||||||
|
|
||||||
|
- [Discord](/docs/discord) — read characters and campaigns from a server.
|
||||||
|
- [Foundry VTT](/docs/foundry) — keep a world and a campaign in step.
|
||||||
|
- [Obsidian](/docs/obsidian) — write campaign notes in your vault.
|
||||||
62
frontend/app/content/docs/03-integrations/02-discord.md
Normal file
62
frontend/app/content/docs/03-integrations/02-discord.md
Normal file
@@ -0,0 +1,62 @@
|
|||||||
|
# Discord
|
||||||
|
|
||||||
|
The Dragonroll Discord bot lets a server read the characters of a campaign without anyone leaving
|
||||||
|
Discord: the roster, a character's sheet with its portrait, and who plays whom. It is a read-only bot —
|
||||||
|
it never changes your campaign.
|
||||||
|
|
||||||
|
## Connecting a server
|
||||||
|
|
||||||
|
1. Invite the bot to the server with the `bot` and `applications.commands` scopes.
|
||||||
|
2. A Discord **administrator** runs `/dragonroll connect`. The bot answers with a *Sign in to
|
||||||
|
Dragonroll* button.
|
||||||
|
3. Whoever opens it signs in to the Dragonroll account that owns the campaign and picks that campaign.
|
||||||
|
The server is now linked to it, and the bot says so.
|
||||||
|
4. From then on anybody in the server can look the campaign's characters up.
|
||||||
|
|
||||||
|
The authorization link lasts ten minutes and works once. A campaign is linked to one Discord server at
|
||||||
|
a time, and a server to one campaign; authorizing the server with a different Dragonroll account takes
|
||||||
|
over the connection.
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
| Command | Who | What it does |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `/characters [type]` | everybody | Lists the characters of the campaign this server is linked to. `type` narrows the list to **Characters**, **NPCs** or **Creatures**. Every character a player has claimed shows up next to that player. |
|
||||||
|
| `/character name [public]` | everybody | Shows one actor's sheet: its portrait, description, race, class and level, background, armor class and speed, ability scores, proficiencies, traits, spells and inventory. Start typing a name and Discord offers the campaign's roster. Set `public` to `true` to show the sheet to the whole channel instead of only to you. |
|
||||||
|
| `/dragonroll connect` | administrators | Asks Dragonroll for the sign-up link that connects this server, and confirms here once somebody has authorized it. |
|
||||||
|
| `/dragonroll link campaign:` | administrators | Moves this server to another campaign of the connected Dragonroll account. Type part of a name to filter the choices. |
|
||||||
|
| `/dragonroll unlink` | administrators | Removes this server's campaign link. The campaign is untouched; the commands simply have nothing to read until one is linked again. |
|
||||||
|
| `/dragonroll status` | everybody | Shows which campaign this server reads, and which character your Discord account holds on it. |
|
||||||
|
| `/dragonroll refresh` | everybody | Asks Dragonroll again where the connection stands, and shows what it answered. |
|
||||||
|
| `/dragonroll assign character:` | everybody | Links a character of the campaign to your Discord account, so the bot knows it is yours and `/characters` says so. You can take a character nobody holds; a character somebody else holds can only be moved by an administrator. |
|
||||||
|
| `/dragonroll unassign [character]` | everybody | Drops a character link. Without the option you give up your own character; naming somebody else's takes it off them, which only an administrator can do. |
|
||||||
|
|
||||||
|
Replies are private: only you see them, so a player can look up their character in a busy channel. The
|
||||||
|
one exception is `/character` with `public:true`, which posts the sheet where everyone can read it — for
|
||||||
|
the villain the party is talking to, or the magic item they just found.
|
||||||
|
|
||||||
|
## Characters and their players
|
||||||
|
|
||||||
|
`/dragonroll assign` is how a player says *this one is mine*:
|
||||||
|
|
||||||
|
- each account holds one character, so claiming a second one frees the first,
|
||||||
|
- a free character can be taken by anybody,
|
||||||
|
- a character somebody holds can only be taken or freed by a server administrator,
|
||||||
|
- the pairing shows up in `/characters` and in `/dragonroll status`, which is what lets the table see
|
||||||
|
who is playing whom.
|
||||||
|
|
||||||
|
Assigning a character does not hide anything: the bot is read-only and every member of the server can
|
||||||
|
already read the campaign's characters with `/character`.
|
||||||
|
|
||||||
|
## When something goes wrong
|
||||||
|
|
||||||
|
| The bot says | What is going on |
|
||||||
|
| --- | --- |
|
||||||
|
| "Connect a Dragonroll account first with /dragonroll connect." | Nobody has authorized this server yet, or the authorization expired before anyone opened it. |
|
||||||
|
| "Only Discord server administrators can connect Dragonroll or change this campaign link." | The command changes the server's connection, so it needs the Discord Administrator permission. |
|
||||||
|
| "The bot API secret is missing or does not match the backend." | Whoever runs the bot has to set the same `DRAGONROLL_DISCORD_BOT_SECRET` in the bot and in the Dragonroll backend. |
|
||||||
|
| "This server does not have a linked campaign." | The link was removed; an administrator has to pick a campaign with `/dragonroll link`. |
|
||||||
|
|
||||||
|
Character portraits are read from Dragonroll's public upload folder, so the bot needs to be able to
|
||||||
|
reach the server Dragonroll runs on. Whoever hosts the bot finds its setup in `discord-bot/README.md`
|
||||||
|
in the source repository.
|
||||||
114
frontend/app/content/docs/03-integrations/03-foundry.md
Normal file
114
frontend/app/content/docs/03-integrations/03-foundry.md
Normal file
@@ -0,0 +1,114 @@
|
|||||||
|
# Foundry VTT
|
||||||
|
|
||||||
|
The Foundry integration keeps a Dragonroll campaign and a Foundry world in step: the world's
|
||||||
|
characters and item directory arrive in the campaign, and what you change in Dragonroll goes back to
|
||||||
|
the world.
|
||||||
|
|
||||||
|
There are two separate parts, and you only need the first of them:
|
||||||
|
|
||||||
|
| Part | What it is |
|
||||||
|
| --- | --- |
|
||||||
|
| The **Dragonroll Foundry API** module | Installed in the world. Links it to a campaign and keeps its actors and items synced. Runs in the game client. |
|
||||||
|
| The optional **snapshot bridge** | A small process on the Foundry host that publishes a read-only snapshot of the world for Dragonroll to browse. Only for reading world data over the API. |
|
||||||
|
|
||||||
|
Character and item sync works without the bridge.
|
||||||
|
|
||||||
|
## Installing the module
|
||||||
|
|
||||||
|
Foundry VTT v12 to v14. Copy the `dragonroll-foundry` folder into
|
||||||
|
`{Foundry user data}/Data/modules/dragonroll-foundry/`, restart Foundry, and enable **Dragonroll
|
||||||
|
Foundry API** in the world's module settings.
|
||||||
|
|
||||||
|
The module's own settings hold two things you set: the **Dragonroll Endpoint** — the address of your
|
||||||
|
Dragonroll server, `https://dragonroll.aranroig.com` by default — and **Dragonroll Auto-sync**, which
|
||||||
|
is on.
|
||||||
|
|
||||||
|
## Linking a world
|
||||||
|
|
||||||
|
Open the world with a GM account. The module asks Dragonroll for a sign-up link and prints it in a
|
||||||
|
notification: open it, sign in, and pick the campaign this world belongs to. **Dragonroll Pairing
|
||||||
|
Status** in the module settings always says where things stand — waiting for a link, connected to a
|
||||||
|
named campaign, or why a link could not be used.
|
||||||
|
|
||||||
|
Worth knowing:
|
||||||
|
|
||||||
|
- The link expires after ten minutes and works once. If it goes unused, reload the world to get a new
|
||||||
|
one.
|
||||||
|
- A world links to one campaign, and a campaign to one Foundry world: linking a second world replaces
|
||||||
|
the first.
|
||||||
|
- The link, the sync token it hands back and the pairing status are all **client** settings: the
|
||||||
|
browser that completed the link is the one that syncs. Another browser on the same world reads as not
|
||||||
|
paired until it links too.
|
||||||
|
- **Dragonroll Pairing Status** is written by the module. It is not a field to fill in.
|
||||||
|
- The campaign shows the linked world's title and system under **Settings → Integrations**, where
|
||||||
|
**Unlink** ends the pairing.
|
||||||
|
|
||||||
|
## What syncs
|
||||||
|
|
||||||
|
| In Foundry | In the campaign |
|
||||||
|
| --- | --- |
|
||||||
|
| Character, NPC and creature actors | Actors with the same sheet: abilities, combat stats, proficiencies, traits, spells, carried gear, portrait |
|
||||||
|
| The world's **item directory** (the items tab) | The campaign's item list, with category, rarity, quantity, weight, properties and description |
|
||||||
|
| The folders grouping that item directory | Item folders with the same names and nesting |
|
||||||
|
| A folder's colour | The campaign's folder colour — and the other way round, what you colour in Dragonroll lands on the world's folder |
|
||||||
|
|
||||||
|
The item list is the world's item directory and nothing else. The gear a character carries is that
|
||||||
|
character's inventory: it travels with the character and stays on its sheet, so a sword a fighter owns
|
||||||
|
does not turn up in the campaign's item list. Spells, classes, subclasses, backgrounds, feats and
|
||||||
|
species are not gear and are not imported.
|
||||||
|
|
||||||
|
An actor or item keeps the Dragonroll id it was given in a `dragonroll-foundry.actorId` /
|
||||||
|
`dragonroll-foundry.itemId` flag, and that is what makes the two sides recognise each other. A world
|
||||||
|
item that carries no flag is matched by name, so a hand-written item in Dragonroll is adopted instead of
|
||||||
|
doubled, and renaming it in either place does not resurrect a duplicate.
|
||||||
|
|
||||||
|
Changes flow both ways as they happen, and Dragonroll's own edits are applied back in Foundry within a
|
||||||
|
few seconds. A **full** snapshot — the one taken when the world links, or forced from the actor
|
||||||
|
directory — is the only thing that prunes: it is the only moment either side can see the whole list and
|
||||||
|
notice what is gone. Live edits never delete anything.
|
||||||
|
|
||||||
|
## Auto-sync, and sending one actor on purpose
|
||||||
|
|
||||||
|
**Dragonroll Auto-sync** is what keeps the two in step: actors and world items you create, change or
|
||||||
|
delete are sent to the campaign, and both sides reconcile every few seconds. Turning it off stops all
|
||||||
|
of it — nothing is sent, and Dragonroll stops rewriting your Foundry documents, so the campaign keeps
|
||||||
|
whatever it already holds. Turn it back on and both sides reconcile again, including the edits queued
|
||||||
|
while it was off.
|
||||||
|
|
||||||
|
To send one character across right now, or to cross over while autosync is off, right-click the actor
|
||||||
|
(or several) in the Foundry actor directory and pick **Dragonroll: Force Sync**. Those actors, with the
|
||||||
|
gear inside them, are pushed immediately. It only upserts: it never prunes the campaign's other actors.
|
||||||
|
Actors Dragonroll does not import — anything that is not a character, NPC or creature — are refused with
|
||||||
|
a notification saying so.
|
||||||
|
|
||||||
|
## Foundry's icons in Dragonroll
|
||||||
|
|
||||||
|
With a world linked, Dragonroll's item icon browser can page through the icon library that world ships
|
||||||
|
with, one folder at a time. If it says the world has no address, set it under **Settings → Integrations
|
||||||
|
→ Foundry VTT URL** in the campaign.
|
||||||
|
|
||||||
|
## The optional snapshot bridge
|
||||||
|
|
||||||
|
The bridge is a small Node.js (18 or newer) process that runs beside Foundry. A GM client publishes the
|
||||||
|
world's actor and item snapshot to it, and Dragonroll reads that snapshot back through its own API, so
|
||||||
|
a server can ask what a world holds without touching the game. It is read-only, it keeps nothing across
|
||||||
|
restarts, and character sync does not depend on it.
|
||||||
|
|
||||||
|
It needs its own tokens — separate ones for publishing and for reading — and an origin allow-list for
|
||||||
|
the Foundry client:
|
||||||
|
|
||||||
|
| Variable | What it is |
|
||||||
|
| --- | --- |
|
||||||
|
| `DRAGONROLL_FOUNDRY_PUSH_TOKEN` | The token the Foundry client publishes with; the backend's `FOUNDRY_API_PUSH_TOKEN` must match it |
|
||||||
|
| `DRAGONROLL_FOUNDRY_READ_TOKEN` | The token reads with; the backend's `FOUNDRY_API_TOKEN` must match it |
|
||||||
|
| `DRAGONROLL_FOUNDRY_ALLOWED_ORIGINS` | The browser origins allowed to publish, comma separated |
|
||||||
|
| `DRAGONROLL_FOUNDRY_HOST` / `DRAGONROLL_FOUNDRY_PORT` | Where the bridge listens; `0.0.0.0:8787` by default |
|
||||||
|
| `DRAGONROLL_FOUNDRY_DATA_PATH` | The Foundry Data directory, which lets the bridge list the core `icons/` library |
|
||||||
|
|
||||||
|
The backend points at it with `FOUNDRY_API_URL` (and `FOUNDRY_API_CLIENT_URL` when the Foundry clients
|
||||||
|
reach it under a different address than the backend does). Once it is set up, Dragonroll answers
|
||||||
|
`GET /api/foundry/world`, `/actors`, `/characters`, `/items`, one of each by id, an actor's embedded
|
||||||
|
items, and `/icons` — all for a signed-in Dragonroll user, and all read-only.
|
||||||
|
|
||||||
|
`dragonroll-foundry/README.md` in the source repository documents the bridge, its routes and its
|
||||||
|
heartbeat in full.
|
||||||
77
frontend/app/content/docs/03-integrations/04-obsidian.md
Normal file
77
frontend/app/content/docs/03-integrations/04-obsidian.md
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
# Obsidian
|
||||||
|
|
||||||
|
The **Dragonroll Sync** plugin moves campaign notes between a Dragonroll campaign and an Obsidian
|
||||||
|
vault: import the campaign so you can read and write it with your own notes, and push the note you are
|
||||||
|
working on back to the campaign.
|
||||||
|
|
||||||
|
It is an explicit, you-ask-for-it workflow. Nothing happens in the background, and the plugin never
|
||||||
|
deletes a note.
|
||||||
|
|
||||||
|
## Installing
|
||||||
|
|
||||||
|
Copy `main.js` and `manifest.json` into your vault:
|
||||||
|
|
||||||
|
```text
|
||||||
|
<vault>/.obsidian/plugins/dragonroll-sync/
|
||||||
|
```
|
||||||
|
|
||||||
|
Then enable **Dragonroll Sync** under Settings → Community plugins. It is plain JavaScript, so there is
|
||||||
|
nothing to build, and it runs on desktop and mobile alike.
|
||||||
|
|
||||||
|
## Connecting
|
||||||
|
|
||||||
|
Under **Settings → Community plugins → Dragonroll Sync**:
|
||||||
|
|
||||||
|
1. Set the **Dragonroll API URL** — `https://dragonroll.aranroig.com/api` by default, or your own
|
||||||
|
server, such as `http://localhost:5000/api`.
|
||||||
|
2. **Sign in** with your Dragonroll username or email and your password. The password is used once to
|
||||||
|
sign in and is not saved; what the plugin keeps is the session token, in this vault, and it expires
|
||||||
|
after 48 hours like any other Dragonroll session.
|
||||||
|
3. Pick the **campaign**. Every import and push works against that campaign.
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
Both are in Obsidian's command palette:
|
||||||
|
|
||||||
|
| Command | What it does |
|
||||||
|
| --- | --- |
|
||||||
|
| **Import or refresh campaign notes** | Brings every note of the campaign into `Dragonroll/<Campaign>/`, folders and nesting included, and updates the ones already there. Imported notes keep their place in the campaign's folder tree. |
|
||||||
|
| **Push active note to Dragonroll** | Sends the note you are in to the campaign: a new root note if it is not linked yet, or an update of the note it is linked to. |
|
||||||
|
|
||||||
|
## How a note knows where it belongs
|
||||||
|
|
||||||
|
An imported note carries three properties in its frontmatter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
dragonrollId: 665f1c…
|
||||||
|
dragonrollCampaign: 665f0a…
|
||||||
|
dragonrollTitle: The Salt Gull
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
They are what ties the file to its note in the campaign: they survive renames, and they are stripped
|
||||||
|
from the markdown the plugin sends back, so they never show up in Dragonroll. Pushing a brand new local
|
||||||
|
note adds them too, which is how the next push updates the same note instead of creating a copy.
|
||||||
|
|
||||||
|
Renaming the note's title in Dragonroll renames the imported file on the next import; renaming the file
|
||||||
|
in Obsidian renames the note in Dragonroll on the next push.
|
||||||
|
|
||||||
|
## Your edits are not overwritten
|
||||||
|
|
||||||
|
The plugin remembers how a note looked the last time it was imported or pushed, and uses that as the
|
||||||
|
baseline:
|
||||||
|
|
||||||
|
| Since the last sync | What the import does |
|
||||||
|
| --- | --- |
|
||||||
|
| Only the campaign's copy changed | The local file is updated |
|
||||||
|
| Only your local file changed | Your file is kept as it is, and reported for you to look at |
|
||||||
|
| Both changed | Your file is kept as it is, and reported for you to look at |
|
||||||
|
| Neither changed | Nothing is touched |
|
||||||
|
|
||||||
|
So a note you were rewriting in Obsidian is never quietly replaced: the plugin leaves it alone and tells
|
||||||
|
you it is waiting. Pushing is the deliberate direction — it writes the active note's current title and
|
||||||
|
content into Dragonroll.
|
||||||
|
|
||||||
|
A note that is linked to a different campaign cannot be pushed while another campaign is selected:
|
||||||
|
switch the campaign in the plugin settings first.
|
||||||
9
frontend/app/pages/[...all].vue
Normal file
9
frontend/app/pages/[...all].vue
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
<script setup>
|
||||||
|
// L'aplicació de finestres no té rutes pròpies: qualsevol adreça que no sigui la
|
||||||
|
// documentació l'obre, i /link/authorize se n'encarrega dins d'AppShell.
|
||||||
|
import AppShell from '~/components/views/AppShell.vue';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<AppShell></AppShell>
|
||||||
|
</template>
|
||||||
8
frontend/app/pages/docs/[slug].vue
Normal file
8
frontend/app/pages/docs/[slug].vue
Normal file
@@ -0,0 +1,8 @@
|
|||||||
|
<script setup>
|
||||||
|
// `/docs/<slug>`, amb el slug del fitxer de markdown (mira ~/services/Docs.js).
|
||||||
|
import DocsView from '~/components/views/DocsView.vue';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<DocsView></DocsView>
|
||||||
|
</template>
|
||||||
7
frontend/app/pages/docs/index.vue
Normal file
7
frontend/app/pages/docs/index.vue
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
<script setup>
|
||||||
|
import DocsView from '~/components/views/DocsView.vue';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<DocsView></DocsView>
|
||||||
|
</template>
|
||||||
7
frontend/app/pages/index.vue
Normal file
7
frontend/app/pages/index.vue
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
<script setup>
|
||||||
|
import AppShell from '~/components/views/AppShell.vue';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<AppShell></AppShell>
|
||||||
|
</template>
|
||||||
114
frontend/app/services/Docs.js
Normal file
114
frontend/app/services/Docs.js
Normal file
@@ -0,0 +1,114 @@
|
|||||||
|
import { Marked } from "marked";
|
||||||
|
import { CreateHeadingSlugger, HeadingsFromMarkdown, TitleFromMarkdown } from "./DocsMarkdown";
|
||||||
|
|
||||||
|
/*
|
||||||
|
The documentation served at /docs is markdown files under app/content/docs, so writing a page means
|
||||||
|
adding a file. The layout of a page's path says everything the sidebar needs:
|
||||||
|
|
||||||
|
app/content/docs/<group>/<NN>-<page>.md
|
||||||
|
|
||||||
|
The folder is the sidebar group and its own number orders the groups, the number in front of the file
|
||||||
|
orders the pages inside its group, and the rest of the file name is the page's slug (`02-discord.md`
|
||||||
|
is `/docs/discord`). A page's title is its first heading, and the first page of the first group is
|
||||||
|
served at `/docs` itself.
|
||||||
|
|
||||||
|
A group's label is looked up under `docs.groups.<folder>` in the locale files of
|
||||||
|
`i18n/locales/en/docs.json` and its siblings, so a new group needs that label in every locale.
|
||||||
|
*/
|
||||||
|
const markdownFiles = import.meta.glob("../content/docs/*/*.md", { query: "?raw", eager: true, import: "default" });
|
||||||
|
|
||||||
|
const Numbered = /^(\d+)-/;
|
||||||
|
const WithoutNumber = (name) => name.replace(Numbered, "");
|
||||||
|
// A name without a number in front sorts after every numbered one in its folder.
|
||||||
|
const OrderOf = (name) => {
|
||||||
|
const numbered = Numbered.exec(name);
|
||||||
|
return numbered ? Number(numbered[1]) : Number.MAX_SAFE_INTEGER;
|
||||||
|
};
|
||||||
|
|
||||||
|
const pages = Object.entries(markdownFiles)
|
||||||
|
.map(([file, source]) => {
|
||||||
|
const [folder, filename] = file.split("/").slice(-2);
|
||||||
|
const markdown = String(source ?? "");
|
||||||
|
|
||||||
|
return {
|
||||||
|
group: WithoutNumber(folder),
|
||||||
|
groupOrder: OrderOf(folder),
|
||||||
|
slug: WithoutNumber(filename).replace(/\.md$/, ""),
|
||||||
|
order: OrderOf(filename),
|
||||||
|
title: TitleFromMarkdown(markdown),
|
||||||
|
headings: HeadingsFromMarkdown(markdown),
|
||||||
|
markdown,
|
||||||
|
};
|
||||||
|
})
|
||||||
|
.sort((left, right) =>
|
||||||
|
left.groupOrder - right.groupOrder || left.order - right.order || left.slug.localeCompare(right.slug)
|
||||||
|
);
|
||||||
|
|
||||||
|
// `/docs` is the first page of the documentation, the rest hang under it by their slug.
|
||||||
|
function GetDocsHref(slug) {
|
||||||
|
return pages.length && slug === pages[0].slug ? "/docs" : `/docs/${slug}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function GetDocsFirstSlug() {
|
||||||
|
return pages.length ? pages[0].slug : "";
|
||||||
|
}
|
||||||
|
|
||||||
|
// The sidebar: one entry per group folder, in reading order, holding its pages.
|
||||||
|
function GetDocsNav() {
|
||||||
|
const nav = [];
|
||||||
|
|
||||||
|
for (const page of pages) {
|
||||||
|
let group = nav.find((entry) => entry.key === page.group);
|
||||||
|
if (!group) {
|
||||||
|
group = { key: page.group, pages: [] };
|
||||||
|
nav.push(group);
|
||||||
|
}
|
||||||
|
group.pages.push({ slug: page.slug, title: page.title, href: GetDocsHref(page.slug) });
|
||||||
|
}
|
||||||
|
|
||||||
|
return nav;
|
||||||
|
}
|
||||||
|
|
||||||
|
const marked = new Marked();
|
||||||
|
|
||||||
|
// Every heading gets the anchor the sidebar and the "on this page" list link to. The slugger is
|
||||||
|
// replaced at the start of a parse so each page numbers its repeated headings on its own: marked
|
||||||
|
// parses one document at a time and does it synchronously, so no other parse can cut in.
|
||||||
|
let slugHeadings = CreateHeadingSlugger();
|
||||||
|
|
||||||
|
marked.use({
|
||||||
|
renderer: {
|
||||||
|
heading({ tokens, depth }) {
|
||||||
|
const content = this.parser.parseInline(tokens);
|
||||||
|
return `<h${depth} id="${slugHeadings(content)}">${content}</h${depth}>`;
|
||||||
|
},
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
function RenderDocsMarkdown(markdown) {
|
||||||
|
slugHeadings = CreateHeadingSlugger();
|
||||||
|
return String(marked.parse(markdown || ""));
|
||||||
|
}
|
||||||
|
|
||||||
|
// What the /docs page shows: a rendered page with the headings it holds and whichever pages come
|
||||||
|
// before and after it, or null when nothing is published under that slug.
|
||||||
|
function GetDocsPage(slug) {
|
||||||
|
const index = pages.findIndex((page) => page.slug === slug);
|
||||||
|
if (index === -1) return null;
|
||||||
|
|
||||||
|
const page = pages[index];
|
||||||
|
const neighbours = (page) => (page ? { slug: page.slug, title: page.title, href: GetDocsHref(page.slug) } : null);
|
||||||
|
|
||||||
|
return {
|
||||||
|
slug: page.slug,
|
||||||
|
group: page.group,
|
||||||
|
title: page.title,
|
||||||
|
// The page's own h1 is in the body already; the list is for its sections.
|
||||||
|
headings: page.headings.filter((heading) => heading.depth > 1 && heading.depth <= 3),
|
||||||
|
html: RenderDocsMarkdown(page.markdown),
|
||||||
|
previous: neighbours(pages[index - 1]),
|
||||||
|
next: neighbours(pages[index + 1]),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
export { GetDocsFirstSlug, GetDocsHref, GetDocsNav, GetDocsPage, RenderDocsMarkdown };
|
||||||
90
frontend/app/services/DocsMarkdown.js
Normal file
90
frontend/app/services/DocsMarkdown.js
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
/*
|
||||||
|
String helpers for the documentation under /docs: the words a heading shows, the anchor it gets, and
|
||||||
|
the headings the sidebar lists. They import nothing at all, not even marked, because the repository
|
||||||
|
root installs no dependencies and `tests/docs.test.js` loads this file straight from source.
|
||||||
|
*/
|
||||||
|
|
||||||
|
// What marked escapes, back to the character it stands for: an anchor has to be the same whether it
|
||||||
|
// was written as `'` or arrived as `'`.
|
||||||
|
const Entities = {
|
||||||
|
amp: "&",
|
||||||
|
lt: "<",
|
||||||
|
gt: ">",
|
||||||
|
quot: '"',
|
||||||
|
apos: "'",
|
||||||
|
nbsp: " ",
|
||||||
|
"#39": "'",
|
||||||
|
"#x27": "'",
|
||||||
|
};
|
||||||
|
|
||||||
|
function DecodeEntities(value) {
|
||||||
|
return value.replace(/&(#?[a-z0-9]+);/gi, (entity, body) => (Entities[body.toLowerCase()] ?? ""));
|
||||||
|
}
|
||||||
|
|
||||||
|
// A heading's anchor is built from its markdown source when the sidebar is built, and from the HTML
|
||||||
|
// marked has rendered when the page is. This drops everything the two forms disagree on — the tags
|
||||||
|
// marked adds, the entities it escapes, and the characters markdown uses for emphasis and links — so
|
||||||
|
// both keep the same words and land on the same anchor.
|
||||||
|
function HeadingText(value) {
|
||||||
|
return DecodeEntities(
|
||||||
|
String(value ?? "")
|
||||||
|
.replace(/<[^>]*>/g, "") // <code>, <em>, <a> … around the heading's words
|
||||||
|
.replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1") // a link keeps the label it shows, not its target
|
||||||
|
.replace(/[*_`~]/g, "") // emphasis
|
||||||
|
).trim();
|
||||||
|
}
|
||||||
|
|
||||||
|
// Lower case letters, numbers and dashes: what a url fragment and a query selector both accept.
|
||||||
|
function Slugify(value) {
|
||||||
|
return HeadingText(value)
|
||||||
|
.toLowerCase()
|
||||||
|
.replace(/[^a-z0-9]+/g, "-")
|
||||||
|
.replace(/^-+|-+$/g, "");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Two headings with the same words cannot share an anchor: the second becomes `words-1`, the third
|
||||||
|
// `words-2`. The sidebar and the renderer both walk a page's headings in document order, so the
|
||||||
|
// numbers they hand out are the same.
|
||||||
|
function CreateHeadingSlugger() {
|
||||||
|
const seen = new Map();
|
||||||
|
|
||||||
|
return (value) => {
|
||||||
|
const base = Slugify(value) || "section";
|
||||||
|
const times = seen.get(base) || 0;
|
||||||
|
seen.set(base, times + 1);
|
||||||
|
return times === 0 ? base : `${base}-${times}`;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// The headings of a markdown document, in order, each with the anchor its renderer will give it:
|
||||||
|
// `{ depth: 2, text: "Link a world", slug: "link-a-world" }`. Lines inside a fenced code block are
|
||||||
|
// skipped — a `# comment` there is shell, not a heading.
|
||||||
|
function HeadingsFromMarkdown(source) {
|
||||||
|
const slug = CreateHeadingSlugger();
|
||||||
|
const headings = [];
|
||||||
|
let inFence = false;
|
||||||
|
|
||||||
|
for (const line of String(source ?? "").split(/\r?\n/)) {
|
||||||
|
if (/^ {0,3}(```|~~~)/.test(line)) {
|
||||||
|
inFence = !inFence;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (inFence) continue;
|
||||||
|
|
||||||
|
const heading = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
|
||||||
|
if (!heading) continue;
|
||||||
|
|
||||||
|
const text = HeadingText(heading[2]);
|
||||||
|
headings.push({ depth: heading[1].length, text, slug: slug(text) });
|
||||||
|
}
|
||||||
|
|
||||||
|
return headings;
|
||||||
|
}
|
||||||
|
|
||||||
|
// A documentation page's title is its first heading.
|
||||||
|
function TitleFromMarkdown(source) {
|
||||||
|
const [first] = HeadingsFromMarkdown(source);
|
||||||
|
return first ? first.text : "";
|
||||||
|
}
|
||||||
|
|
||||||
|
export { CreateHeadingSlugger, HeadingsFromMarkdown, HeadingText, Slugify, TitleFromMarkdown };
|
||||||
15
frontend/i18n/locales/ca/docs.json
Normal file
15
frontend/i18n/locales/ca/docs.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"title": "Documentació",
|
||||||
|
"contents": "Contingut",
|
||||||
|
"on-this-page": "En aquesta pàgina",
|
||||||
|
"open-app": "Obrir Dragonroll",
|
||||||
|
"previous": "Anterior",
|
||||||
|
"next": "Següent",
|
||||||
|
"not-found": "No hi ha cap pàgina de la documentació que es digui «{page}».",
|
||||||
|
"back-to-docs": "Tornar a la documentació",
|
||||||
|
"groups": {
|
||||||
|
"getting-started": "Primers passos",
|
||||||
|
"using-dragonroll": "Fer servir Dragonroll",
|
||||||
|
"integrations": "Integracions"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,6 +2,7 @@
|
|||||||
"main-menu": "Menú principal",
|
"main-menu": "Menú principal",
|
||||||
"edit-profile": "Editar perfil",
|
"edit-profile": "Editar perfil",
|
||||||
"create-campaign": "Crear campanya",
|
"create-campaign": "Crear campanya",
|
||||||
|
"documentation": "Documentació",
|
||||||
"log-out": "Tanca la sessió",
|
"log-out": "Tanca la sessió",
|
||||||
"settings": "Configuració",
|
"settings": "Configuració",
|
||||||
"exit": "Sortir"
|
"exit": "Sortir"
|
||||||
|
|||||||
15
frontend/i18n/locales/en/docs.json
Normal file
15
frontend/i18n/locales/en/docs.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"title": "Documentation",
|
||||||
|
"contents": "Contents",
|
||||||
|
"on-this-page": "On this page",
|
||||||
|
"open-app": "Open Dragonroll",
|
||||||
|
"previous": "Previous",
|
||||||
|
"next": "Next",
|
||||||
|
"not-found": "There is no documentation page called “{page}”.",
|
||||||
|
"back-to-docs": "Back to the documentation",
|
||||||
|
"groups": {
|
||||||
|
"getting-started": "Getting started",
|
||||||
|
"using-dragonroll": "Using Dragonroll",
|
||||||
|
"integrations": "Integrations"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,6 +2,7 @@
|
|||||||
"main-menu": "Main menu",
|
"main-menu": "Main menu",
|
||||||
"edit-profile": "Edit profile",
|
"edit-profile": "Edit profile",
|
||||||
"create-campaign": "Create Campaign",
|
"create-campaign": "Create Campaign",
|
||||||
|
"documentation": "Documentation",
|
||||||
"log-out": "Log out",
|
"log-out": "Log out",
|
||||||
"settings": "Settings",
|
"settings": "Settings",
|
||||||
"exit": "Exit"
|
"exit": "Exit"
|
||||||
|
|||||||
15
frontend/i18n/locales/es/docs.json
Normal file
15
frontend/i18n/locales/es/docs.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"title": "Documentación",
|
||||||
|
"contents": "Contenido",
|
||||||
|
"on-this-page": "En esta página",
|
||||||
|
"open-app": "Abrir Dragonroll",
|
||||||
|
"previous": "Anterior",
|
||||||
|
"next": "Siguiente",
|
||||||
|
"not-found": "No hay ninguna página de la documentación que se llame «{page}».",
|
||||||
|
"back-to-docs": "Volver a la documentación",
|
||||||
|
"groups": {
|
||||||
|
"getting-started": "Primeros pasos",
|
||||||
|
"using-dragonroll": "Usar Dragonroll",
|
||||||
|
"integrations": "Integraciones"
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,6 +2,7 @@
|
|||||||
"main-menu": "Menú principal",
|
"main-menu": "Menú principal",
|
||||||
"edit-profile": "Editar perfil",
|
"edit-profile": "Editar perfil",
|
||||||
"create-campaign": "Crear campanya",
|
"create-campaign": "Crear campanya",
|
||||||
|
"documentation": "Documentación",
|
||||||
"log-out": "Cerrar sesión",
|
"log-out": "Cerrar sesión",
|
||||||
"settings": "Configuración",
|
"settings": "Configuración",
|
||||||
"exit": "Salir"
|
"exit": "Salir"
|
||||||
|
|||||||
328
tests/docs.test.js
Normal file
328
tests/docs.test.js
Normal file
@@ -0,0 +1,328 @@
|
|||||||
|
// Tests for the documentation under /docs (Syndria98/dragonroll#79): the markdown pages are the
|
||||||
|
// documentation, so what has to stay right is (1) the pages are well formed — a title, a slug, a
|
||||||
|
// numbered group, translations for the group's label, and no link pointing at a page that does not
|
||||||
|
// exist, (2) the page about an integration really documents what that integration offers, which is
|
||||||
|
// checked against the sources that define it: the slash commands of discord-bot/src/commands.js and
|
||||||
|
// the commands the Obsidian plugin registers, and (3) the routes: /docs and /docs/<slug> render the
|
||||||
|
// documentation and every other address still opens the window app.
|
||||||
|
//
|
||||||
|
// `frontend/app/services/DocsMarkdown.js` is the pure part of the docs (headings, slugs, titles) and
|
||||||
|
// is loaded straight from source, the way the other tests load the frontend services; it imports
|
||||||
|
// nothing, so the repository root's no-dependencies rule holds. `Docs.js` itself is not loaded: it
|
||||||
|
// reads the markdown through `import.meta.glob`, which only Vite can answer.
|
||||||
|
//
|
||||||
|
// Run with `npm test` from the repository root, or `node --test tests/`.
|
||||||
|
|
||||||
|
const { test } = require("node:test");
|
||||||
|
const assert = require("node:assert/strict");
|
||||||
|
const fs = require("node:fs");
|
||||||
|
const path = require("node:path");
|
||||||
|
const vm = require("node:vm");
|
||||||
|
|
||||||
|
function readRepoFile(...parts) {
|
||||||
|
return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadDocsMarkdown() {
|
||||||
|
const source = readRepoFile("frontend", "app", "services", "DocsMarkdown.js");
|
||||||
|
return vm.compileFunction(source.replace("export {", "return {") , [], {
|
||||||
|
parsingContext: vm.createContext({}),
|
||||||
|
})();
|
||||||
|
}
|
||||||
|
|
||||||
|
const docs = loadDocsMarkdown();
|
||||||
|
|
||||||
|
// The documentation pages, as the folder layout defines them.
|
||||||
|
const docsRoot = path.join(__dirname, "..", "frontend", "app", "content", "docs");
|
||||||
|
const docPages = fs.readdirSync(docsRoot, { withFileTypes: true })
|
||||||
|
.filter((entry) => entry.isDirectory())
|
||||||
|
.sort((left, right) => left.name.localeCompare(right.name))
|
||||||
|
.flatMap((group) => fs.readdirSync(path.join(docsRoot, group.name))
|
||||||
|
.filter((file) => file.endsWith(".md"))
|
||||||
|
.sort()
|
||||||
|
.map((file) => ({
|
||||||
|
group: group.name.replace(/^\d+-/, ""),
|
||||||
|
slug: file.replace(/^\d+-/, "").replace(/\.md$/, ""),
|
||||||
|
markdown: fs.readFileSync(path.join(docsRoot, group.name, file), "utf8"),
|
||||||
|
}))
|
||||||
|
);
|
||||||
|
|
||||||
|
const slugs = new Set(docPages.map((page) => page.slug));
|
||||||
|
const groups = [...new Set(docPages.map((page) => page.group))];
|
||||||
|
|
||||||
|
const pageAbout = (slug) => docPages.find((page) => page.slug === slug);
|
||||||
|
|
||||||
|
// --- The heading helpers the sidebar and the anchors are built from ---
|
||||||
|
|
||||||
|
test("a heading's slug comes out of its words, whatever form they arrive in", () => {
|
||||||
|
assert.equal(docs.Slugify("Link a world"), "link-a-world");
|
||||||
|
assert.equal(docs.Slugify(" Auto-sync, and one actor "), "auto-sync-and-one-actor");
|
||||||
|
assert.equal(docs.Slugify("Dragonroll: Force Sync!"), "dragonroll-force-sync");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the anchor built from a heading's markdown is the one built from its HTML", () => {
|
||||||
|
// The sidebar slugs the markdown source and the renderer slugs what marked produced, so the two
|
||||||
|
// have to land on the same anchor for a sidebar link to land on its section.
|
||||||
|
const pairs = [
|
||||||
|
["**Link** a `world`", "<strong>Link</strong> a <code>world</code>"],
|
||||||
|
["Commands & characters", "Commands & characters"],
|
||||||
|
["[Foundry](/docs/foundry) worlds", '<a href="/docs/foundry">Foundry</a> worlds'],
|
||||||
|
["It's here", "It's here"],
|
||||||
|
];
|
||||||
|
|
||||||
|
for (const [markdown, html] of pairs) {
|
||||||
|
assert.equal(docs.Slugify(markdown), docs.Slugify(html), `slug of ${markdown}`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("repeated headings get distinct anchors, in the order they are written", () => {
|
||||||
|
const slug = docs.CreateHeadingSlugger();
|
||||||
|
assert.equal(slug("Setup"), "setup");
|
||||||
|
assert.equal(slug("setup"), "setup-1");
|
||||||
|
assert.equal(slug("Setup"), "setup-2");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the headings of a page are listed in order, with their anchors", () => {
|
||||||
|
const headings = docs.HeadingsFromMarkdown([
|
||||||
|
"# Connecting a service",
|
||||||
|
"",
|
||||||
|
"## How a connection works",
|
||||||
|
"text",
|
||||||
|
"### What it allows",
|
||||||
|
"```sh",
|
||||||
|
"# not a heading",
|
||||||
|
"```",
|
||||||
|
"## Next",
|
||||||
|
].join("\n"));
|
||||||
|
|
||||||
|
// The service is loaded from another realm, so the values are copied out before being compared.
|
||||||
|
assert.deepEqual(
|
||||||
|
JSON.parse(JSON.stringify(headings.map(({ depth, text, slug }) => ({ depth, text, slug })))),
|
||||||
|
[
|
||||||
|
{ depth: 1, text: "Connecting a service", slug: "connecting-a-service" },
|
||||||
|
{ depth: 2, text: "How a connection works", slug: "how-a-connection-works" },
|
||||||
|
{ depth: 3, text: "What it allows", slug: "what-it-allows" },
|
||||||
|
{ depth: 2, text: "Next", slug: "next" },
|
||||||
|
]
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a page takes its title from its first heading", () => {
|
||||||
|
assert.equal(docs.TitleFromMarkdown("# Your first campaign\n\n## Signing in"), "Your first campaign");
|
||||||
|
assert.equal(docs.TitleFromMarkdown("no heading here"), "");
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- The pages themselves ---
|
||||||
|
|
||||||
|
test("the documentation has pages, in numbered groups", () => {
|
||||||
|
assert.ok(docPages.length >= 5, `expected several documentation pages, found ${docPages.length}`);
|
||||||
|
|
||||||
|
for (const page of docPages) {
|
||||||
|
const folder = `${page.group}`;
|
||||||
|
assert.ok(folder.length > 0, `${page.slug} sits in an oddly named folder`);
|
||||||
|
assert.match(page.slug, /^[a-z0-9]+(-[a-z0-9]+)*$/, `${page.slug} is not a url-friendly slug`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("every page has a title, and no two pages share a slug", () => {
|
||||||
|
const seen = new Set();
|
||||||
|
|
||||||
|
for (const page of docPages) {
|
||||||
|
const title = docs.TitleFromMarkdown(page.markdown);
|
||||||
|
assert.ok(title, `${page.slug} has no heading to title it`);
|
||||||
|
assert.ok(!seen.has(page.slug), `${page.slug} is published twice`);
|
||||||
|
seen.add(page.slug);
|
||||||
|
}
|
||||||
|
assert.equal(seen.size, docPages.length);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("every page has sections, which is what the sidebar lists beside it", () => {
|
||||||
|
for (const page of docPages) {
|
||||||
|
const sections = docs.HeadingsFromMarkdown(page.markdown).filter((heading) => heading.depth > 1);
|
||||||
|
assert.ok(sections.length, `${page.slug} has no section headings to list`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("every group has a sidebar label in every locale", () => {
|
||||||
|
const labels = ["en", "es", "ca"].map((locale) =>
|
||||||
|
JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "docs.json"))
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.ok(labels.every((label) => label.groups), "each docs.json namespace needs a `groups` object");
|
||||||
|
|
||||||
|
for (const group of groups) {
|
||||||
|
for (const label of labels) {
|
||||||
|
const text = label.groups[group];
|
||||||
|
assert.ok(text, `the "${group}" group has no label in its docs.json`);
|
||||||
|
assert.notEqual(text, group, `the "${group}" label is untranslated`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the pages only link to pages that are published", () => {
|
||||||
|
for (const page of docPages) {
|
||||||
|
for (const link of page.markdown.matchAll(/\]\((\/docs\/?[a-z0-9-]*)\)/g)) {
|
||||||
|
const target = link[1].replace("/docs/", "");
|
||||||
|
if (!target) continue; // /docs itself
|
||||||
|
assert.ok(slugs.has(target), `${page.slug} links to ${link[1]}, which is not published`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the three integrations each have their own page", () => {
|
||||||
|
for (const slug of ["discord", "foundry", "obsidian"]) {
|
||||||
|
assert.ok(pageAbout(slug), `${slug} has no documentation page`);
|
||||||
|
}
|
||||||
|
assert.ok(pageAbout("connecting-a-service"), "the shared way of connecting a service is undocumented");
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- The integrations pages describe what the integrations actually offer ---
|
||||||
|
|
||||||
|
// discord-bot/src/commands.js builds the slash commands with discord.js, which the repository root
|
||||||
|
// does not install: the builder is stubbed by one that records the names it is given.
|
||||||
|
function loadSlashCommands() {
|
||||||
|
const registered = [];
|
||||||
|
|
||||||
|
class Builder {
|
||||||
|
constructor() {
|
||||||
|
this.name = "";
|
||||||
|
this.parent = null;
|
||||||
|
this.children = [];
|
||||||
|
this.optionNames = [];
|
||||||
|
}
|
||||||
|
|
||||||
|
setName(name) { this.name = name; return this; }
|
||||||
|
setDescription() { return this; }
|
||||||
|
setContexts() { return this; }
|
||||||
|
setRequired() { return this; }
|
||||||
|
setMaxLength() { return this; }
|
||||||
|
setAutocomplete() { return this; }
|
||||||
|
addChoices() { return this; }
|
||||||
|
addStringOption(configure) { configure(new Builder()); return this; }
|
||||||
|
addBooleanOption(configure) { configure(new Builder()); return this; }
|
||||||
|
addSubcommand(configure) {
|
||||||
|
const sub = new Builder();
|
||||||
|
sub.parent = this;
|
||||||
|
configure(sub);
|
||||||
|
this.children.push(sub);
|
||||||
|
return this;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
class SlashCommandBuilder extends Builder {
|
||||||
|
constructor() {
|
||||||
|
super();
|
||||||
|
registered.push(this);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const moduleStub = { exports: {} };
|
||||||
|
vm.compileFunction(readRepoFile("discord-bot", "src", "commands.js"), ["require", "module", "exports"])(
|
||||||
|
(id) => {
|
||||||
|
if (id === "discord.js") return { InteractionContextType: { Guild: 0 }, SlashCommandBuilder };
|
||||||
|
throw new Error(`require("${id}") is not stubbed`);
|
||||||
|
},
|
||||||
|
moduleStub,
|
||||||
|
moduleStub.exports
|
||||||
|
);
|
||||||
|
|
||||||
|
const names = [];
|
||||||
|
for (const command of registered) {
|
||||||
|
names.push(command.name);
|
||||||
|
for (const sub of command.children) names.push(`${command.name} ${sub.name}`);
|
||||||
|
}
|
||||||
|
return names;
|
||||||
|
}
|
||||||
|
|
||||||
|
test("the Discord page lists every command the bot declares", () => {
|
||||||
|
const about = pageAbout("discord");
|
||||||
|
const commands = loadSlashCommands();
|
||||||
|
|
||||||
|
// Sanity check on the stub before it is trusted to list anything.
|
||||||
|
assert.ok(commands.includes("characters"), `expected the bot's commands, got ${commands.join(", ")}`);
|
||||||
|
assert.ok(commands.includes("dragonroll connect"));
|
||||||
|
|
||||||
|
for (const command of commands) {
|
||||||
|
assert.ok(
|
||||||
|
about.markdown.includes("`/" + command),
|
||||||
|
`the Discord page does not document /${command}`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// The Obsidian plugin registers each command palette entry with `this.addCommand({ id, name, … })`.
|
||||||
|
function loadObsidianCommands() {
|
||||||
|
const source = readRepoFile("obsidian-plugin", "main.js");
|
||||||
|
const commands = [...source.matchAll(
|
||||||
|
/this\.addCommand\(\{\s*id:\s*["']([^"']+)["'],\s*name:\s*["']([^"']+)["']/g
|
||||||
|
)].map((match) => ({ id: match[1], name: match[2] }));
|
||||||
|
|
||||||
|
// Sanity check on the extraction before it is trusted to list anything.
|
||||||
|
assert.ok(commands.length >= 2, `expected the plugin's commands, got ${commands.length}`);
|
||||||
|
|
||||||
|
return commands;
|
||||||
|
}
|
||||||
|
|
||||||
|
test("the Obsidian page lists the commands the plugin registers", () => {
|
||||||
|
const about = pageAbout("obsidian");
|
||||||
|
|
||||||
|
for (const command of loadObsidianCommands()) {
|
||||||
|
assert.ok(
|
||||||
|
about.markdown.includes(`**${command.name}**`),
|
||||||
|
`the Obsidian page does not document "${command.name}" (${command.id})`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the Foundry page covers what the world and the campaign do with each other", () => {
|
||||||
|
const about = pageAbout("foundry").markdown;
|
||||||
|
|
||||||
|
for (const topic of ["Auto-sync", "Force Sync", "item directory", "Pairing Status"]) {
|
||||||
|
assert.ok(about.includes(topic), `the Foundry page never mentions ${topic}`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- The routes ---
|
||||||
|
|
||||||
|
test("the app renders whichever page the address asks for", () => {
|
||||||
|
const root = readRepoFile("frontend", "app", "app.vue");
|
||||||
|
assert.match(root, /<NuxtPage\s*\/?>/, "app.vue has to render the matched page");
|
||||||
|
assert.doesNotMatch(root, /CreateWindow/, "the window app boots from AppShell, not from app.vue");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the documentation has a route of its own, and the app keeps the rest", () => {
|
||||||
|
const pages = path.join("frontend", "app", "pages");
|
||||||
|
const docsRoutes = ["docs/index.vue", "docs/[slug].vue"];
|
||||||
|
|
||||||
|
for (const route of docsRoutes) {
|
||||||
|
assert.match(
|
||||||
|
readRepoFile(pages, route),
|
||||||
|
/<DocsView\s*\/?>/,
|
||||||
|
`${route} has to render the documentation`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
for (const route of ["index.vue", "[...all].vue"]) {
|
||||||
|
assert.match(
|
||||||
|
readRepoFile(pages, route),
|
||||||
|
/<AppShell\s*\/?>/,
|
||||||
|
`${route} has to open the window app`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// The catch-all is what keeps /link/authorize, and every path a service already links to, alive.
|
||||||
|
const shell = readRepoFile("frontend", "app", "components", "views", "AppShell.vue");
|
||||||
|
assert.ok(shell.includes("/link/authorize"), "the service link screen has to stay reachable");
|
||||||
|
assert.ok(shell.includes("/discord/authorize"), "the legacy Discord link has to stay reachable");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the main menu points at the documentation", () => {
|
||||||
|
const menu = readRepoFile("frontend", "app", "components", "windows", "MainMenuWindow.vue");
|
||||||
|
assert.match(menu, /href="\/docs"/, "the main menu has to link to /docs");
|
||||||
|
assert.match(menu, /main-menu\.documentation/);
|
||||||
|
|
||||||
|
for (const locale of ["en", "es", "ca"]) {
|
||||||
|
const strings = JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "main-menu.json"));
|
||||||
|
assert.ok(strings.documentation, `${locale} has no label for the documentation link`);
|
||||||
|
}
|
||||||
|
});
|
||||||
Reference in New Issue
Block a user