# The Markdown Paginel reads and writes

Paginel reads **CommonMark + GitHub Flavored Markdown** and writes Markdown that GitHub, Pandoc,
Obsidian or VS Code render well, and that reads back as **the same document**. Write what you
would write for GitHub; use the extensions below when you need more.

## Supported

| Document | Markdown |
|---|---|
| Headings 1 to 6 | `#` … `######` (a deeper heading is written `######`) |
| Bold, italic, strikethrough | `**b**`, `*i*`, `~~s~~` |
| Underline | `<u>u</u>` |
| Superscript, subscript | `m<sup>2</sup>`, `H<sub>2</sub>O` |
| Colour, font, size of a passage | `<span style="color:#c01c28;font-family:Georgia;font-size:14pt">…</span>` |
| Links, inline code | `[text](url)`, `` `code` `` |
| Lists | `- item`, `1. item`, `- [ ] task`, nested by indentation |
| Quote, code block | `> …`, fenced code |
| Table | GFM table (one line per cell; several paragraphs in a cell: `<br data-p>`) |
| Image | `![alt](data:image/png;base64,… "120x40")` (size in points), or `image:<id>` for an image already in the document |
| Image placement (Word's own) | In the image's title, items separated by `;`: `![Plan](image:3f2a "right; width 40%; gap 12pt")`. One place: `inline` (default), `left`, `right` (text around), `center` (alone on its lines), `top`, `bottom` (of the page), `behind` (under the text), `page X Y`, `margin X Y` (from the page edge or the margins; X may be `left`/`center`/`right`, Y `top`/`center`/`bottom`). Settings: `width 6cm` or `width 40%` (of the text width; the height follows), `height L`, `wrap around\|above-below\|none`, `gap L` (distance to the text; 1, 2 or 4 values as in CSS), `rotate DEG`, `flip h\|v`. Units `pt`, `mm`, `cm`, `in`. The image stays in its paragraph: put it at the paragraph's start, alone on its line. A title with anything else is an ordinary title (the image stays in the line) |
| Footnote | `[^1]` and `[^1]: note` |
| Page break | `<div style="page-break-after: always"></div>` (or `\newpage`) |
| Alignment | `<!-- align: center -->` on the line before the paragraph |
| Line break inside a paragraph | `\` at the end of the line |

## What you will see when you read

- **Section annotations.** `GET /api/docs/{doc}` puts
  `<!-- section id=12 owner=agent:redacteur -->` before each section heading. They tell you the ids you
  need for `…/sections/{id}`. **Leave them out of what you write.**
- **Images by reference.** Images come as `image:<id>`, short, so you do not read megabytes of base64.
  To keep an image where it is, keep its `![](image:<id>)` line. A new image goes in as a `data:` address.
  `GET …/markdown` embeds the images as base64 unless you add `?images=reference`.
- **Attachments of a board's cards.** A file attached to a card is a paragraph of one link,
  `[report.pdf](attachment:<id>)`, at the end of the card. Keep it as it is when you write the card back; never
  write one yourself (`POST /api/agent/files?board=&card=` attaches a file and writes its link).
- **Front matter** (whole-document reads and writes only): a YAML block at the top with `paper`,
  `orientation`, `margins`, `header`, `footer`, `template`, `background`, `author`, `lang`, `title`.
  Do not touch it when writing a single section.

## How a write is applied

- `PUT …/sections/{id}`:
  - **no headings** in your Markdown: it replaces the section's own **body**; its sub-sections are kept;
  - **deeper headings** (a level below the section): it becomes the section's **whole new content**;
    a heading with the same title as an existing sub-section keeps that sub-section (same id, same
    owner); sub-sections delegated to someone else stay as they are and end up after your content;
    reusing the title of such a section is refused.
- `PUT …/markdown` replaces the **entire document**: only for a person's request or a document you create.
  It is refused wherever you may not write, and it forgets the original `.docx` the document came from.
- `POST …/edit` replaces one exact passage, which must appear **exactly once**, in one
  paragraph; `new_text` is plain text on one line and takes the passage's formatting.

## What Markdown cannot carry

Spacing, tab stops, numbering styles, text boxes and Word-only table formatting (widths, merged
cells, borders) are not in the Markdown. They stay in the document and are not lost by editing
around them, but you cannot read or set them through Markdown. Floating images are the exception:
their place is in their title (above), read and written. Spacing, indents, line spacing, « keep with
next » and page breaks of paragraphs are set by `POST /api/docs/{doc}/layout` (below).

## Layout: what a person says → operations

`POST /api/docs/{doc}/layout` (`references/api.md`) takes these operations; `GET …/layout` gives the image ids,
the section ids and the alerts, each with its `fix`. Translate, apply (`"dry_run": true` when the request is
ambiguous), **look at the pages** (`"images": "changed"`, or `GET …/pages/{n}.png`), fix, then say what you did.

| The person says | Operations |
|---|---|
| « la photo à droite, sur un tiers » · "the photo on the right, a third of the width" | `{"op": "image", "image": "image:<id>", "place": "right; width 33%"}` |
| « l'image au milieu, seule sur sa ligne » · "the picture centred, on its own" | `{"op": "image", "image": "image:<id>", "place": "center"}` |
| « remets l'image dans le texte » · "put the image back in the line" | `{"op": "image", "image": "image:<id>", "place": "inline"}` |
| « mets la photo à côté du paragraphe sur les ventes » · "move the photo next to the sales paragraph" | `{"op": "image", "image": "image:<id>", "to": {"section": 12, "text": "Les ventes"}}` (an exact passage of that paragraph) |
| « le logo en haut à droite de la première page » · "the logo top right of the first page" | `{"op": "image", "image": "image:<id>", "place": "margin right top; width 3cm", "to": {"text": "<words of the first paragraph>"}}` |
| « en filigrane » · "as a watermark" | on one page: `{"op": "image", …, "place": "behind; page center center; width 80%"}`; on every page: `{"op": "page", "background": "image:<id>", "background-fit": "contain"}` |
| « pas de titre seul en bas de page » · "no heading alone at the bottom of a page" | send the `fix` of each `heading_alone` alert of the report (a heading is always kept with its next paragraph; a page break after it is what leaves it alone) |
| « aère les paragraphes » · "give the paragraphs some air" | `{"op": "paragraph", "all": true, "space_after": "10pt", "line": "1.15"}` (`section` to limit it to a part) |
| « justifie le texte » · "justify the text" | `{"op": "paragraph", "all": true, "align": "justify"}` |
| « le chapitre 2 sur une nouvelle page » · "start chapter 2 on a new page" | `{"op": "paragraph", "section": 12, "text": "<the heading>", "page_break_before": true}` |
| « marges de 2 cm » · "2 cm margins" | `{"op": "page", "margins": "2cm"}` |
| « en paysage » · "landscape" | `{"op": "page", "orientation": "landscape"}` |
| « numéro de page en bas, au centre » · "page numbers at the bottom, centred" | `{"op": "page", "footer": "{PAGE} / {PAGES}", "footer-align": "center"}` |
| « tout en Georgia 11 » · "everything in Georgia 11" | `{"op": "styles", "normal": {"font": "Georgia", "size": "11pt"}, "heading1": {"font": "Georgia"}, "heading2": {"font": "Georgia"}}`; a font Paginel lacks gives a `font_missing` alert (another font's widths: lines may break otherwise than in Word) |
| « les titres en bleu » · "blue headings" | `{"op": "styles", "heading1": {"color": "#1F4E79"}, "heading2": {"color": "#1F4E79"}}` |
| « le modèle Entreprise » · "the corporate template" | `{"op": "template", "name": "<a name of /api/templates>"}` |

Several operations go in one call (one step for the person). The page, the styles and the template need the
`document` scope; images and paragraphs, the right to write their part. What Word cannot write is refused with
the reason.
