Write the article (Markdown, mathematics, figures)

A Cabdell article is plain text: Markdown with LaTeX formulas, plus its own files. That keeps it readable by any tool, today and in thirty years. This page says what you can write and how it is shown. To publish it, see publish an article; terms such as CID, IPFS and gateway are explained in the glossary.

The folder

A publication is a folder with:

index.md, required: the text, in Markdown, starting with a header;
assets/, optional: figures, data files, anything the text refers to. Sub-folders inside assets/ are allowed.

Rules:

Nothing else may sit next to index.md.
At most 20 MB in total. Data that would make the article larger can go in a separate dataset publication, which has the same limit.
No hidden files (names starting with a dot) and no symbolic links.
UTF-8 text with Unix line endings; the web app takes care of this when you write in the Upload tab.
Avoid spaces in file names: fig-1.svg, not fig 1.svg.

In the Upload tab, every file you add goes straight into assets/ under its own name. To use sub-folders, build the folder yourself and publish it with “I have a CID”.

The header

index.md starts with a header between two lines that contain only ---. In the Upload tab the app writes it from the publication form, so you only write the title and the abstract:

---
title: "Heart-rate recovery after repeated sprints"
authors: ["YOUR_ADDRESS", "CO_AUTHOR_ADDRESS"]
field: 0x0303
secondary_field: 0x0501
type: article
parent: 0
abstract: "One paragraph that says what was done and what was found."
keywords: ["sprint", "heart rate, recovery"]
references: ["https://doi.org/10.1000/example"]
license: CC-BY-4.0
language: en
---

Every key, and the syntax rules, are in the article header.

Text

The text is Markdown (CommonMark with the GitHub extensions). The title comes from the header, so sections start at level 2 (##).

You write	You get
`## Methods`, `### Subjects`	section and sub-section headings
a blank line between paragraphs	separate paragraphs
a backslash `\` at the end of a line	a line break inside a paragraph
`italic`, `bold`, `~~struck~~`, `code`	emphasis, strong, struck-through, monospaced
lines starting with `-` or `1.`	bulleted or numbered lists (indent by two spaces to nest)
`- [ ] to do` / `- [x] done`	checklists
`> quoted text`	a quotation block
three backticks, the language name, the code, three backticks	a code block (monospaced, without colours)
rows of cells separated by vertical bars, with a line of dashes under the first row	a table; colons in the dashes line align a column (`:---:` centred, `---:` right)
`a claim[^1]` and, anywhere, `[^1]: the note`	a numbered footnote, listed at the end of the article

When the article has at least three headings of level 2 or 3, its page shows a Contents list built from them, and the page gives a reading time at 220 words a minute.

Mathematics

Formulas are LaTeX, rendered with KaTeX.

Inline: $E = mc^2$ .
Displayed (centred, on its own line): a line with only $$, the formula, a line with only $$:
```
$$
\int_0^1 x\,dx = \tfrac{1}{2}
$$
```
$$ ... $$ written on a single line comes out inline, not centred.
Most LaTeX mathematics works: fractions, roots, sums, integrals, Greek letters, \mathbb{R}, \text{...}, matrices (\begin{pmatrix} ... \end{pmatrix}), aligned equations (\begin{aligned} ... \end{aligned}).
Not available: $ ... $ and \[ ... \] as delimiters, equation numbers and \label / \ref, and document-wide macros (\newcommand works only inside the formula where it is written).
A literal dollar sign is written \$. Subscripts and chemistry go in math: $\mathrm{H_2O}$ , $\dot{V}O_{2\,max}$ .

Figures

Put the file in assets/ and write:

![Figure 1: heart rate during the six sprints](assets/fig-1.svg)

*Figure 1.* Heart rate during the six sprints; the shaded band is the standard deviation.

The text in brackets is the alternative text, read aloud by screen readers and shown if the image cannot load; the paragraph below is the visible caption.

SVG, PNG, JPG, GIF and WebP are shown. Prefer SVG for charts, and keep each image under a few megabytes.
Images from other websites (https://...) are not embedded: they are shown as a link (“external image not shown”), because an external image can change, disappear or be used to follow readers.

Links

To the web: [text](https://example.org/page), which opens in a new tab. E-mail: [text](mailto:name@example.org).
To a file of your publication: [raw data](assets/data.csv). Readers download it from the Cabdell gateway.
To another Cabdell article: its full address, for example [earlier study](https://cabdell.press/testnet/a/12). An amendment’s link to its parent article is added automatically.

References and citations

Write your references as a visible numbered list in a ## References section, with the DOI link of each work. The references key of the header keeps them as data too, but it is not shown.

Citations between Cabdell articles are counted: an article cites another when it links to its page, writes its DOI (https://doi.org/10.5281/zenodo.123 or 10.5281/zenodo.123), writes the CID of one of its versions, or amends it. The references list of the header counts too. See citations and Thread Score and cite an article.

What is not supported

HTML. Tags are ignored: inside a sentence their text stays and the tag disappears (<sub>2</sub> becomes 2); a block of HTML such as <div>...</div> disappears with its content. There are no scripts, frames, embedded videos (link to the video instead), colours or fonts.
Links to a heading inside the text (#methods).
Showing files other than images inside the text: link them instead, [the protocol](assets/protocol.pdf).
Link types other than web addresses, mailto: and files of your publication: they are removed.

Reviews and comments

Reviews and comments use the same Markdown and mathematics, with three differences:

each is a single text of at most 256 KiB (262 144 bytes);
there is no assets/ folder, so they cannot show images (an image is shown as a link);
they are pinned where your articles are, so set up your storage first (Storage (IPFS) on your profile, or the publish page).

In comments, @name.algo or @ADDRESS mentions a person and notifies them; see comment, mention and vote.