Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s

This commit is contained in:
Gitea OpenCode Agent
2026-10-15 19:07:09 +00:00
parent a8a1e0ca41
commit 788f69efd3
27 changed files with 1731 additions and 70 deletions

View File

@@ -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).

View File

@@ -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.

View 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.