Skip to content
ARIADNEARIADNEARIADNE Docs

The article header (front-matter)

Every ARIADNE publication is a folder whose index.md starts with a short header, the front-matter. The web app writes the header for you from the publication form, so most authors only type the title and the abstract. This page is the complete reference for people who write the header by hand, build tools, or audit what the indexer accepts.

The authority is section 3 of the publishing guide (in the app at https://ariadne.press/testnet/guide). The web app (projects/web/src/lib/frontmatter.ts) and the indexer (projects/indexer/src/content.ts) parse the header with the same code, so what the web app accepts before you sign is what the indexer accepts afterwards. Terms such as CID and on-chain are explained in the Glossary.

The folder

Section titled “The folder”

A publication is a folder with exactly this layout:

my-article/
  index.md          required: the text, in Markdown, starting with the header
  assets/           optional: figures, data files, anything the text refers to
    fig-1.svg
    data/
      table.csv     sub-folders inside assets/ are allowed
Rule Detail
index.md Required, at the root of the folder.
assets/ Optional. Sub-folders are allowed. Refer to files by relative path (assets/fig-1.svg), never by an external URL.
Nothing else No other file or folder may sit next to index.md.
Size At most 20 MB in total (the code counts 20 × 1024 × 1024 = 20 971 520 bytes). Larger material goes in a separate dataset publication.
Hidden files Not allowed (names starting with a dot), and no symbolic links.
Text encoding UTF-8 with Unix line endings. The web app takes care of this in the Upload tab.
File names Avoid spaces (fig-1.svg, not fig 1.svg).

Everything in the folder is public and permanent, including comments in the source (<!-- ... -->) and every file in assets/. A new version adds a new folder; the old one stays readable.

The folder is turned into one content identifier (CID) with fixed parameters, and that CID is what the blockchain stores. See Storage: IPFS, pins and copies for the idea and Verify without trusting ariadne.press for the commands that recompute it.

What is checked, and where

Section titled “What is checked, and where”
Check Web app, before signing Indexer, after publication
index.md at the root refuses to continue malformed
Only index.md and assets/ refuses to continue not checked (the CID already fixes the content)
No hidden entries refuses to continue hidden files are left out when the CID is recomputed
Total size refuses above 20 MB oversized
The files hash to the declared CID computes the CID itself otherwise unavailable, with a notice
The header is readable refuses to continue malformed
Header values against the chain refuses until they match mismatch

Header syntax

Section titled “Header syntax”

The header sits between two lines that contain only ---, at the very top of index.md:

---
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
---


## Introduction

The rules, from the publishing guide and the shared parser:

  • The first line of index.md is --- (a UTF-8 byte-order mark before it is tolerated). The header ends at the next line that starts with ---.

  • One key: value per line, in lower case, starting at the beginning of the line. Keys are case-sensitive: Title is not title.

  • Text goes in double quotes ("..."). Inside it you may use :, # and commas, but not a double quote; use single quotes around the whole value instead: title: 'The "fast" protocol'.

  • A value without quotes is read as text (type: article, license: CC-BY-4.0).

  • Lists go in brackets, ["a", "b"], or one item per line below the key, each starting with two spaces and - :

    keywords:
      - sprint
      - "heart rate, recovery"

    Commas inside quoted items do not split them. List items are always read as text.

  • Numbers are written in decimal (771) or hexadecimal (0x0303).

  • # outside quotes and brackets, at the start of a line or after a space, starts a comment until the end of the line.

  • null or ~ means “no value”. A key followed by nothing always starts a block list, so write secondary_field: 0 or leave the line out: secondary_field: alone is read as an empty list and does not equal 0.

  • Any other kind of line (an indented key, a nested map) makes the whole header unreadable, and the indexer marks the article malformed.

Keys

Section titled “Keys”
Key Required Type Checked against the chain What it is
title yes text no The title shown on the article page, in the feed, in search and in citations. The web app refuses to sign without it.
authors yes list of Algorand addresses first address: yes; the rest: a notice only The first is the wallet that publishes, then the declared co-authors. The web app checks that each is a valid address.
field yes number yes The primary field, for example 0x0303. The list is in Fields and at https://ariadne.press/testnet/fields.
secondary_field no number yes A second field, or 0 or absent for none. It must differ from field.
type yes article, notes, amendment, dataset or replication yes The kind of publication.
parent yes number yes 0, except for an amendment: the number of the article it amends.
abstract recommended text no One paragraph, shown under the title in the feed and searched.
keywords no list of text no Searched, offered as search filters, copied to a Zenodo draft.
references no list of text no DOIs, URLs or CIDs, kept as data and counted as citations (see below). They are not shown: write a visible References section too.
license recommended text (an SPDX licence name) no For example CC-BY-4.0.
language recommended text (a language code) no For example en or es.

Any other key is read without error and ignored.

What each key becomes in the indexer

Section titled “What each key becomes in the indexer”
Key Stored as Limits applied by the indexer
title, abstract the article’s title and abstract used only when the value is text
keywords a list of words used only when the value is a list
references part of the version’s references (content.refs_json) up to 500 URLs, 500 DOIs and 500 CIDs per version, text and header together
language lower-cased cut to 16 characters
license as written, trimmed cut to 64 characters
the body plain text for search cut to 200 000 characters

What must match the on-chain declaration

Section titled “What must match the on-chain declaration”

The publish() call stores the fields, the type and the parent on the blockchain, and those values are canonical. The indexer reads the header of every version and compares:

Header key On-chain value How they are compared
field primary_field equal as numbers (0x0303 and 771 are the same)
secondary_field secondary_field equal as numbers; an absent key counts as 0
type article_type (1 to 5) the name must be the one of the stored number
parent parent_article equal as numbers; an absent key counts as 0
authors[0] the publishing wallet (author) the same 58-character address, exactly
authors[1...] the co-authors declared in publish() compared only to show a notice: “front-matter authors[] differs from the on-chain co-authors”

The title is never compared: the chain does not store it.

The result is the content’s validation status, shown on the article page and returned by the API as content.validation_status:

Status Meaning
valid The folder hashes to the CID, index.md and its header are readable, and the checked values match.
mismatch One of the checked values differs from the chain. The notice names which ones.
malformed index.md is missing, or its header is missing or unreadable.
unavailable The content could not be fetched, or the bytes obtained do not hash to the CID.
oversized The folder is larger than 20 MB.

Content that is not valid is shown with a warning and never hidden; the article stays valid on the blockchain. The web app refuses to sign until the header matches the form, and its “Fill the header from the form” button rewrites the checked keys for you. A new version (allowed while the article is a preprint or under review) must keep the same values; “New version” in the app starts from the current files with the checked keys rewritten from the article.

On the blockchain, authorship is the list of accepted authors (the submitter plus the co-authors who confirmed), not the authors list. The header list is frozen with each version: it says whom the submitter intended when that version was published. See Co-authors.

The references key

Section titled “The references key”

references is a list of texts, each one a DOI, a URL or a CID:

references:
  - "https://doi.org/10.5281/zenodo.123"
  - "https://ariadne.press/testnet/a/12"
  - "bafybeidzsrohfscy7xlt4dh53j3kmlxunjl3r2354pvtfn6pysnjpmduna"

The indexer takes every web address, DOI (10. followed by a prefix, a slash and a suffix) and CID it finds in these texts and in the body of the article, links included. It then decides which of them point to another ARIADNE article of the same network. An article cites another when its current version:

  • links to the other article’s page on this network, for example https://ariadne.press/testnet/a/12 on TestNet;
  • writes a DOI that the other article declared, unless that DOI’s record contradicts it;
  • writes the CID of one of the other article’s versions;
  • or amends it (the parent recorded on the blockchain).

An article never cites itself, and citing articles that were retracted are not counted. The citations are recomputed whenever content, versions, DOIs or their checks change. They feed “cited by” on each article and the Thread Score (see Citations and Thread Score).

Items that are not text are ignored. The references list is data only: readers never see it, so keep a visible ## References section with the DOI link of each work, as described in Write the article.

The language and license keys

Section titled “The language and license keys”

language records the language the article is written in, as a short code (en, es). English is the protocol’s language of publication, and the key lets search filter by language. The indexer stores it in lower case.

license names the licence under which you publish, as an SPDX identifier such as CC-BY-4.0. Search can filter by it, and a Zenodo draft prepared from the article uses it, lower-cased, as the record’s licence (Zenodo falls back to cc-by-4.0 when the value holds anything other than letters, digits, ., + and -). Neither key is checked against the chain.

Templates

Section titled “Templates”

Article, dataset and replication

Section titled “Article, dataset and replication”

spec/article-template.md, used for article, dataset and replication:

---
title: ""
authors: ["ADDRESS_1", "ADDRESS_2"]   # informative, frozen per version; first MUST be the submitter (section 7.6)
field: 0x0303                         # MUST equal on-chain primary_field
secondary_field: 0x0501               # MUST equal on-chain secondary_field (omit if 0)
type: article                         # MUST equal on-chain type (article | dataset | replication)
parent: 0                             # MUST equal on-chain parent_article (0 for article/dataset/replication)
abstract: ""
keywords: []
references: []                        # list of {cid | doi | url}
license: CC-BY-4.0
language: en
---


## Introduction


...


## Methods


...


## Results


Figures and data MUST live inside this directory and be referenced by relative path,
for example `![Figure 1](assets/fig1.svg)` or `[data](assets/data.csv)`. Never link external assets.


## Discussion


...


## References


...

Fill title before publishing: an empty title is refused by the web app.

Notes and amendment

Section titled “Notes and amendment”

spec/notes-template.md, used for notes and amendment:

---
title: ""
authors: ["ADDRESS_1"]   # informative, frozen per version; first MUST be the submitter (section 7.6)
field: 0x0303            # MUST equal on-chain primary_field
type: notes              # notes | amendment (MUST equal on-chain type)
parent: 0                # amendment: MUST equal the parent article_id (non-zero); notes: MUST be 0
abstract: ""
---


## Body


...

An amendment’s fields should match those of the article it amends; the web app enforces this, the contract does not.

The template of the Upload tab

Section titled “The template of the Upload tab”

The Upload tab builds index.md from the publication form: the header carries the five checked keys exactly as you chose them (authors with the declared co-authors, field, secondary_field, type, parent), plus title: "Title", a placeholder abstract, keywords: [], references: [], license: CC-BY-4.0 and language: en. The body follows the type:

Type Sections of the starting text
article Introduction, Methods, Results (with a figure and an equation as examples), Discussion, References
notes Notes, References
amendment What this amendment changes, Details, References
dataset Description, Files, How the data were collected, Reuse
replication Original study, Methods, Results, Conclusion, References

A complete example

Section titled “A complete example”
---
title: "Heart-rate recovery after repeated sprints"
authors: ["YOUR_ADDRESS", "CO_AUTHOR_ADDRESS"]
field: 0x0303            # Health sciences
secondary_field: 0x0501  # Psychology
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
---


## Methods


Twelve athletes ran six sprints ([raw data](assets/data.csv)).


![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.


## References


1. Author, *Title*, Journal (Year). https://doi.org/10.1000/example

Replace YOUR_ADDRESS with the address of the wallet that signs, and CO_AUTHOR_ADDRESS with each co-author you declare in the form, in any order after the first. For everything that goes below the header (Markdown, mathematics, figures), see Write the article; for the steps of publishing, see Publish an article.