Writing a magazine issue
How an issue is written in Markdown so the engine reads its cover, ads, sections and articles. Your words are set exactly as written; the design only decides how they look. The short version, with looks, ads and print, is in Help.
A magazine issue is one Markdown file, like any other document, written so its parts can be read: the cover, the ads, the sections and the articles. Your words are set exactly as written. Nothing is rewritten, trimmed or reordered; the design only decides how they look.
Headings work like this: # is the magazine's name, ## starts a section, ### starts an article or an ad, and #### is a subhead inside an article. Nothing goes deeper than ####.
The frontmatter
The file can start with a short block of settings between two --- lines:
---
issue:
date: "November 2026"
number: "Issue 14"
price: "$16.99 US"
advertisements:
- "Maison Ardent"
- "Solène Paris"
---advertisements:lists every ad by its heading, exactly as it is printed (the brand). You decide what is an ad; the design only decides how an ad page looks.issue:describes the issue: its date, number and price. It is printed only where your own text says it (the issue line, below).- If the pictures are illustrations made with an image generator rather than photographs, add
publication:withimagery: illustrative.
In reading order
- The title,
# VELOUR: the magazine's name, which becomes the masthead. - The issue line: the paragraph right after the title, for example
The Atelier Issue · November 2026 · $14.99 US. - Cover lines (optional): a list right after the issue line, three to five items, each with a bold lead:
- **The long coat returns:** why winter belongs to the tailors. - The cover picture (optional): the first picture after the title and before any
##or###, with an optional caption in italics under it. - Front ads (optional):
###ads before the first##section. The first is the inside front cover; any others follow before the contents. - Sections,
## Front of Book,## Features, … in reading order. - Articles and ads,
### …inside the sections, in the order they are printed. An ad that is the very last thing in the document is the outside back cover; an ad right before it is the inside back cover. - Subheads,
#### …inside articles.
An article
### The Long Coat Returns
*Why the season's most serious garment is also its most romantic.*
By Mara Ellison · Photographs by Teo Vance
Body paragraphs…

*Camel double-faced wool coat, Maison Ardent. Leather gloves, Solène Paris.*
#### A subhead- The dek: the first paragraph after the heading, wholly in italics. It must come before any picture, or it is read as that picture's caption.
- The byline: the next short paragraph, starting
By. - The lead picture: a picture before the first paragraph of text, or else the article's first picture.
- Captions: a paragraph wholly in italics directly under a picture.
- Interviews: questions are paragraphs wholly in bold; answers are plain paragraphs.
- Listings: lists whose items start with a bold lead, for example
- **Fri 16 Oct · The Chapel** — …. - Product runs and portfolios: pictures one after another, each with its caption.
- Poems: a
###title, aBy …byline, then the stanzas. Each stanza is one paragraph; end each line with a backslash to keep the line break. Spaces at the start of a line are not kept. - A sign-off: a short closing paragraph, such as
— Celeste Arnaud, Editor-in-Chief.
An ad
### Maison Ardent

**The Winter Collection**
Paris · Milan · New York- The heading is the brand as printed, and it is listed under
advertisements:. Exactly one picture follows directly under it, then at most about 90 words: a headline, one or two short lines, and small print. - Ads carry no web addresses.
When a document is read as an issue
A document is read as an issue when its frontmatter lists ads or has an issue: block, or when two or more of its articles have a dek or a byline, at least one of them a byline such as “By Ana Ruiz” (or the issue line names the issue, as in “The Winter Issue”). The project page then says Recognised as a magazine issue and shows its structure beside the pages.