Images
Every image in a campaign has a page of its own: a title, a Markdown description, pins that link back into the wiki, and an audience. An article that shows the picture is one place it appears, not the only one.
Uploading
Upload images from the campaign menu, in either of two ways:
Path | What it takes |
|---|---|
Sync a folder | A folder of Markdown articles and image files from your own machine |
Import | A package |
Folder sync uploads every image it finds, and each Markdown file becomes an article, unless it is an image's sidecar. Articles arrive as drafts unless you untick Land as drafts, so a sync changes nothing the campaign reads until you publish; images are the exception and upload straight away. Images in a folder called portraits are typed Portrait, so the gallery's type filter gathers them. Files has the matching rules and the review that follows.
The readable formats are PNG, JPEG, GIF, BMP, WebP, TIFF, TGA, QOI and PBM. Any other file in the folder is ignored without a message, so check the result list if something you expected is missing. A very large image won't upload — the limit counts pixels rather than bytes, roughly 30 megapixels — so downscale a huge map first.
You have one storage allowance for the images you upload, shared across every campaign you are in. Withdrawing an image frees none of it, because the file is kept.
Image Content
An image's page holds a written record of its own, and everything GMTales knows about the picture is read from it. A picture can be found and read before any article shows it.
The content is the uploader's alone to edit, from the image's page, and it is written the same way as an article:
What is read from this text:
Part | Syntax | Effect |
|---|---|---|
Title | The first | Shown in the gallery and on the image's page |
Key |
| A stable name to reference it by. See Referencing by key |
Visibility |
| Says who may open the image. See Who can see an image |
Type |
| Files the image under one category in the gallery |
Labels |
| Tags it for the gallery's filters. See Labels |
Credits |
| Attribution, shown on the image's page |
Secrets | A | Hides a passage of the description. See Secrets in a description |
Description | Everything else | The prose shown on the image's page |
With no # heading the image has no title, and its file name is shown in its place.
Credits are declared here, because they belong to whoever uploaded the picture. An article's image block does not take them. Credits are re-read whenever you save the content, so deleting the directive clears the credit.
How it differs from an article
The description is written and read like an article, with four differences.
Article names in it become links. Name Corin Vale in a map's description and the name links to his article. See Linking.
It takes the formatting blocks. Box, columns, quote and secret all work here.
It takes a narrower set of directives: the seven in the table above. Anything else is a validation error (parsing is strict here as everywhere).
It keeps no history. An article records every revision; an image's description is replaced when you save it. See History.
Sidecar file
An image's content can travel with the file. Put a Markdown file in the same folder with the same base name — a sidecar — and it becomes that image's content on upload:
Everything you can write in the editor you can write here, and it is read the same way:
A sidecar is optional; a Markdown file whose name matches no image beside it is read as an article instead.
Who can see an image
An image is read by whoever can read a place it is shown. An image has these places:
Its own page, open to the groups its
visibilitydirective names.Every paragraph, image block, marker, region and drill-down in an article that shows it.
Every note that shows it, read by the people who can read that note.
Add those audiences together and you have who can see the image, in the gallery and as a file.
A freshly uploaded image is shown nowhere, so only you can see it. Place it in an article or a note, or give it a visibility directive naming a group; until you do one of those, the picture is yours.
Showing an image somewhere shares it with that place's readers: put a picture in a public article and it is public, whatever its own directive says. An image's visibility adds an audience and never removes one.
It also follows that you can only show an image you can already see; the first placement is always the uploader's. Referencing someone else's private picture is the same validation error as one that does not exist: Image 'X' is not in this campaign.
Show a picture only inside a secret block and it is read by that secret's readers. Remove the last article that showed it and it is yours alone again.
The same rules govern the file, not only the gallery listing. A picture's link is made for the person who opened the page that shows it, and it stops working a while after. Save the link and it keeps working until then, so treat one you have copied out as a copy of the picture. A link is never made for a picture the reader cannot see.
Uploading is open to the Creator, game masters and players.
Editing is the uploader's alone. Title, key, description, visibility, type and credits belong to whoever uploaded the image, not to a GM or the Creator. See Content Belongs to Its Author.
Labels are the exception: anyone who can see an image can label it from an image block in their own article. See Labels.
Secrets in a description
A secret block hides a passage of the description from anyone outside the group it names. Use it when part of what you have to say about a picture is not for the table:
Players see only the first paragraph, with no gap where the second was. Game masters see both.
Showing an image in an article
An article shows an image by naming it. Standard Markdown is the plainest form: the alt text prints under the picture, and the file joins the gallery with no stored description, labels or pins:
An image block is the same reference with a caption, labels and pins attached.
Image references
Every image reference resolves to an uploaded image the same way. A reference is a standard Markdown image, an image block's src, a portrait or parent directive, a region's child, or a standalone marker's image. Each is matched through a three-tier lookup:
File name, always tried first
Key, from
<!-- key: … -->in the image's contentTitle, the first
#heading in the image's content
Directory parts are ignored, so ../images/maps/stonewatch-map.webp and stonewatch-map.webp are the same file-name reference. That is what lets one Markdown file work in two places: locally you write the relative path your editor needs, and GMTales resolves the bare name.
Your article source is never rewritten. Resolution happens at display time.
Upload the image before you reference it, and make sure you can see it: a reference matching no image you can read is a validation error. To write the article first, save it without the reference and add it once the image is up.
Referencing by key
Assign a key in the image's content:
Then reference the image anywhere without its file name:
Keys survive file renames. Upload a replacement under a new file name, keep the key, and no article needs an edit. Keys are unique within a campaign.
Image blocks
An image block places a picture and carries its record: a caption, a description, labels and pins.
This renders as the picture captioned Greenhearth. The image joins the gallery with the paragraph as its description, and the article is recorded as showing it.
The caption is the block's first heading, at any level. With no heading the first paragraph becomes the caption, so the block below captions the picture with that sentence rather than describing it; with neither, the caption is Figure:
What an image block can contain
The block's header takes a src and an optional thumbnail (see Arguments). Everything in the body has one job:
Part | Syntax | What it does |
|---|---|---|
Caption | First heading, at any level | Printed under the image in the article |
Description | Paragraphs | Describes the image in the gallery and on its page |
Labels |
| Tags the image; feeds the gallery filters. See Labels |
Markers |
| Points of interest. See Markers |
Regions | A | Clickable areas. See Regions |
Nesting |
| Nests another image inside this one. See Nested images |
type, key, visibility and the credits cannot be set from a block — they belong to the image's own content, where they stay the uploader's — and article directives are validation errors here too.
Labels
A labels directive inside the block tags the image, and the gallery's filter badges are built from those tags; the surrounding article keeps its own labels.
Labels are the one thing about somebody else's image you may write. A label is read by the people who can read the passage it sits in, so one written inside a secret block is part of that secret, in the gallery's filters as much as anywhere else. Editing an image's description rewrites only the labels written there; labels written in other people's articles stay theirs.
Article thumbnail
Add thumbnail to make the image the article's thumbnail in overview lists:
An article has one thumbnail; a second thumbnail block is a validation error.
A thumbnail declared inside a secret block is listed only to that secret's readers, so everyone else sees the article in the list without a picture.
Artifacts
A marker, a region and a nested image are all pinned to a picture, at a point or over an area, and the same rules cover them.
Coordinates are percentages of the image's width and height, not pixels. 50,50 is the centre of any image, whatever its size, and each of the two numbers falls between 0 and 100.
An artifact belongs to the passage that declared it and is read by that passage's readers. A pin written inside a secret block is absent from the map for everyone else. Withdraw the article and the pin goes with it.
It takes that passage's dates as well: several dated pins of one article draw as a trail across the picture, in date order, the latest solid and the earlier ones faded.
To give one point two audiences, declare it twice at the same coordinates, each in its own passage. The two arrive as a single pin the reader can page through: a game master sees both entries, a player one.
Each block prints the picture where it stands, so a game master reading that article sees the map twice. Pins reach the image's page from whichever article declares them, so put the second block in the article the secret belongs to.
Markers
A marker is a point on the picture, clicked to show its text. Inside an image block, the single-line form takes a position, an optional description and an optional icon:
The block form carries a longer description, and takes an icon as its second argument. It goes inside the image block, alongside any single-line markers:
A position is one argument, so its two numbers are bound by a comma: 48,30. Markers close together are grouped into one pin.
An article can also drop a marker onto an image with no image block, by naming the image as the second argument:
Placed in the Redwater article, this pins Redwater onto the Greymarch map. The image is required, because a marker with only a position has no map to sit on. This is the marker's second argument list: outside an image block it takes position and image, inside one position, description and icon.
Marker blocks and region blocks belong inside an image block and are validation errors outside one; there, use the single-line marker form.
A marker wears the icon mapped to the type of the article that placed it, so pins from your location articles all look alike. An icon argument overrides that for one pin. See Marker icons.
Regions
A region covers an area instead of a point. It shows its text on hover, and is declared as a block inside an image block:
Coordinates are x,y pairs separated by spaces, three pairs at least. Regions link back to their article the way markers do.
A child argument makes the region open a more detailed map when clicked:
The Draw Region button in the sidebar of the image's page writes the coordinates for you: draw the polygon on the map, then copy the directive it produces into your article.
Nested images
Inside an image block, the parent directive declares that image the parent of another, nesting the named child, at a position if you give one:
Markers from the Harrowfeld and Sorrel maps appear on the Greymarch map at those positions, along with the markers of anything nested inside them. This is how a continent map carries its realms, and a realm map its cities.
A region's child argument writes the same nesting from an area rather than a point, and the two can be mixed on one map.
Gallery
The gallery shows the campaign's images as a thumbnail grid. Reach it from Gallery in the campaign navigation, or from any image's page. Badge filters narrow it by type and by labels. The badges offered are the images' own types and labels together with those of the articles that show them, so an image nobody has typed or labelled is still found by what its articles are typed and labelled. An image shown in two articles carries both their types.
A label written inside a secret block is only offered to the group that block names, as the passage itself is. Search matches a file name, a type, a label, the text written about an image where it is shown, and the titles of the articles that show it.
In a World, the gallery gathers the images of every campaign you can read.
Clicking an image opens its page. The sidebar's Draw region and marker-copy buttons are there for anyone who can open the page, because the directive they write goes in your own article; editing the content and withdrawing or deleting the image are the uploader's alone.
Removing an image
The uploader has two removals, both in the Control panel. Nobody else has either, whatever their role.
Withdraw Image hides the image without destroying it. It leaves the gallery, search, and every article that showed it. Restore Image brings it back exactly as it was. The file stays stored, keeps its name and key so nothing else can claim them, and still counts towards your storage allowance. See Withdrawing.
Delete Image removes it for good. The file is deleted, the image stops counting towards your storage allowance, and its name and key become free for a new upload. There is no way back.