Images
Images are first-class objects with titles, Markdown descriptions, and optional markers. Any image referenced in an article also appears in the campaign gallery, so visual assets stay easy to find and reuse.
Image References
Every image reference in an article — standard Markdown images, image blocks, portrait, parent, and standalone markers — resolves to an uploaded image using a three-tier lookup:
File name (always tried first — backward-compatible)
Key (
<!-- key: ... -->in the image's Content)Title (the first
#heading in the image's Content)
Directory parts are always ignored: ../images/maps/helms-deep-map.webp and helms-deep-map.webp are the same file-name reference.
This is what lets one Markdown file serve both worlds:
Locally, you write whatever relative path makes the image render in your editor.
On the web, GMTales strips the path and resolves by file name, then key, then title.
The relative path satisfies the local editor; the file name helms-deep-map.webp satisfies GMTales. Your article source is never rewritten — resolution happens at display time.
Referencing by key
Assign a key in the image's Content:
Then reference it anywhere without using the file name:
Keys survive file renames — upload a replacement under a new name, keep the same key, and your articles need no edits.
Sizes and Formats
The upload dialog accepts JPEG (.jpg, .jpeg), PNG (.png), and WebP (.webp).
Each upload is stored in up to three versions; which ones exist depends on the source size:
Version | Used For | Created When | Resolution |
|---|---|---|---|
Small | Gallery thumbnails | Always | Downscaled to ≤ ~1 megapixel |
Medium | Inline article images | Source larger than 400×400 | Downscaled to ≤ ~8 megapixels |
Large | Detail view | Source larger than 1200×1200 | Original |
GMTales serves the best available version for each context.
Image Content
Images are more than a pixel payload — each image can carry a title and a Markdown description, turning it into a queryable object in its own right. This is especially useful for images with no Article reference yet, such as a newly uploaded map waiting to be placed.
Edit image content from the image detail view: click Edit in the sidebar (visible to the uploader). A single text area opens — write everything there, the same way you write Articles and Notes.
Four things the server reads from this text:
Part | Syntax | Effect |
|---|---|---|
Title | First | Shown in the gallery and detail view |
Key |
| Stable reference name; must be unique within the campaign |
Visibility |
| Controls who can see this image (same values as Secrets: |
Description | Everything else | Rendered as Markdown in the detail view sidebar |
The full text is stored verbatim. Title and visibility are re-parsed on every save — changing the # heading changes the gallery title; clearing the directive makes the image public again.
Provenance
Images can carry attribution metadata: artist (free text), source (URL or description of where the image came from), and license (e.g. CC-BY 4.0). All three fields are optional and are included in all image API responses.
Sidecar file
Upload a .md companion file alongside the image — it must share the same base name:
The sidecar is the image's Content, delivered at upload time. Everything you can write in the web editor you can write in the sidecar: title, key, visibility, description, and provenance. The upload handler stores the file verbatim and runs the same parse pipeline.
A missing sidecar is fine — it is always optional. A sidecar whose base name does not exactly match the image file name (ignoring extension) is silently ignored.
Folder import
When importing a folder from the Import page, sidecar pairing happens automatically: the importer scans the selected folder for .md files and attaches each one to the image with the matching base name before upload. Images with a found sidecar show a sidecar badge in the file list.
For individual file selection (rather than a full folder), include both the image and its .md file in the same selection and they will be paired the same way.
Image blocks
Provenance fields can also be declared or overridden inside an image Block in an Article, using the same directive keys:
Last write wins per field across both authoring paths.
Image Blocks
An image block is the richest way to place an image — caption, description, and markers are all preserved in the gallery.
The image renders inline with the heading as caption and the description below; it becomes a gallery item, and backlinks record which articles reference it.
Type and Labels
An image block is nearly as metadata-rich as an article: type and labels directives inside the block classify the image itself, and the gallery's filter badges are built from them.
Article Thumbnail
Add thumbnail as a block parameter to make the image the article's thumbnail in overview lists:
Standard Markdown images still work for simple cases — the file appears in the gallery, but without markers or a rich description:
Markers
Markers add interactive points of interest — essential for maps.
Inside an Image Block
Single-line form, with an optional short description as a third part:
Block form for longer descriptions (shown as a popup when the marker is clicked):
Add as many markers as you need — tightly clustered markers are grouped visually.
From Article Text
An article can also drop a marker onto an image without an image block, by naming the image as the third part:
Placed in the Edoras article, this pins Edoras onto the Middle-earth map. The marker is tied to the placing article — it follows that article's lifecycle and visibility.
Regions
Regions are polygon overlays on a map — clickable, label-hovering areas that work like markers but cover an area instead of a point. A region is declared as a block inside an image block or article article:
Coordinates are x,y pairs in percentage space (0–100), separated by spaces. A minimum of three pairs is required.
Regions auto-link to the enclosing article (like markers) and respect segment visibility — a region inside a secret block is only visible to readers who can see that block.
Child image drill-down
Add a child: parameter to make a region navigate to a more detailed map when clicked:
Clicking the region on the parent map opens helms-deep-map.webp directly.
Drawing regions with the authoring tool
Manually computing polygon coordinates is tedious. Use the Draw Region button in the image detail view sidebar:
Click Draw Region — the button turns red and the cursor changes.
Click on the map to place vertices. A dashed green polygon preview follows your cursor.
Close the polygon by clicking near the first vertex (snap circle), or by double-clicking. At least three vertices are required before you can close.
The polygon enters edit mode: drag any vertex (green square handle) to fine-tune it. Click the white midpoint circle on any edge to insert a new vertex there.
The Region directive panel in the sidebar shows the generated text, updating live as you drag. Copy it to the clipboard with the button, then paste it into your article.
Click Discard or press Escape to exit without copying anything.
Nested Images
Inside an image block, the parent directive declares that image the parent of another, nesting the named child at a position:
Markers from the Rohan and Gondor maps (including their own nested images, recursively) appear on the Middle-earth map at the given positions — ideal for hierarchical maps (continent → realm → city).
Gallery
The gallery shows all campaign images as a thumbnail grid. Reach it from the campaign menu, from an article's View Gallery link, or from any image detail view.
It supports the same tools as article lists: badge filters for image type and labels (set in image blocks, see above), and a search that matches the file name, type, labels, descriptions, and referencing article titles.
Image Detail View
Clicking an image opens the detail view: full resolution, title and description, type and labels, uploader and date, interactive markers, and backlinks to referencing articles. With permission, you can edit metadata or delete the image here.
Uploading
Three upload paths are available:
Path | Best for |
|---|---|
Article editor — Upload Image | Adding one image while writing; inserts a reference into the article automatically |
Gallery — Upload Image | Adding one image to the library without immediately referencing it |
Import page | Bulk uploading a folder of images at once, optionally with sidecar files |
The Import page (reached from the campaign menu) supports three separate import flows: general images, portraits, and Markdown articles. For images and portraits, select a folder or individual files. The page preserves any nested subfolder paths as the image's stored path, keeping your local directory structure intact in the gallery. Sidecar .md files in the same folder are paired and uploaded automatically — see Sidecar file above.
Permissions
Gallery and API access follows a union-of-grants rule: an image is visible to a viewer if any of the following is true:
The viewer is the uploader.
The image has no own visibility directive (the default — public to all campaign members).
The image's visibility directive names a group the viewer belongs to, or
meand the viewer is the uploader.Any alive Article segment that references the image is public or accessible to the viewer.
The last point means a referencing segment can open up visibility beyond what the image's own directive restricts. If an image is marked <!-- visibility: me --> but a public Article segment references it in an image block, every campaign member who can see that segment also sees the image in the gallery.
Upload: creators, GMs, and players.
Edit and delete: uploaders manage their own images; GMs and creators manage more broadly.