Skip to content

Authoring Markdown syntax

New to Folio? Start here

Markdown syntax

You can author graph content in Markdown. As you type, Folio maps the Markdown document's elements into RDF, the format Folio's graph is built on. This lets you see the document in Graph View, query its content, validate it against your domain model and link to it from other files.

To decide how your Markdown is interpreted, pick a mapping. A mapping determines how each Markdown element maps to RDF. Folio comes with default mappings for notes, domain models, taxonomies and vocabularies. For example, under the Taxonomy Map, a ## heading becomes a concept scheme and a list item becomes a concept. Mappings can be fully configurable: you can write your own and pick what each element becomes.

The document below is written under the Taxonomy Map, which reads it as a SKOS taxonomy. Graph shows the RDF Folio produces from it in Folio's Graph View, and Turtle shows that RDF as text.

Product Catalog.md
# Product Catalog
::mappedBy Taxonomy Map

## Product Categories

- Electronics
  ::preferred label "Électronique"@fr

  Powered devices and gadgets sold in the catalog.

  - Computers

Markdown syntax and meaning

Mappings read the Markdown elements below. What each one becomes in the graph depends on the mapping you pick.

# Product Catalog
A heading, level 1. The # heading stands for the document: under every mapping Folio ships, its text is the document's title. Write one per document.
## Product Categories
A heading, level 2. Each ## heading is a section under the title. In the Taxonomy Map it becomes a concept scheme, in the Schema Map a class, and in the Note Map a section other documents can link to.
### country
A heading, level 3. Each ### heading is a section under the nearest ## heading above it. In the Schema Map it becomes a property of the class above.
- Electronics
A list item. An item under the heading above it. In the Taxonomy Map it becomes a concept in the scheme above, and its text becomes the concept's English preferred label, "Electronics"@en. In the Vocabulary Map it becomes a term.
- Computers
A list item, indented under another. An item under the item above it. In the Taxonomy Map, the item above becomes its broader concept. The Vocabulary Map ignores the nesting.
Powered devices and gadgets sold in the catalog.
A paragraph. Text under a heading, or under a list item's first line, describes that heading or item: a concept's definition in the Taxonomy Map, a class's or property's description in the Schema Map.

Folio special syntax

Folio adds two pieces of syntax to Markdown: fields (::) and links to entities ([[). The editor shows both by their labels, and the file stores the addresses behind them.

Fields (::)

A field is a line that starts with ::, then a link to a property, then one or more values:

Folio
::[property link] "value"

A field sets that property on the title, heading or list item it sits under, and each value adds one statement to the graph.

To add a field, type :: at the start of a line. A list appears showing the prefixed name, label and description of each property that fits what the field sits under, and Folio writes the link for the one you pick. If no vocabulary in the workspace defines the property, the field still adds its statement, and the editor shows the property's address instead of a label.

Fields and their values work the same in every mapping.

Field placement

Where you put a field decides what it describes. Under a list item, indent it to the item's text. It can follow the item, the item's paragraph or a blank line.

Product Catalog.md
# Product Catalog
::mappedBy Taxonomy Map
<!-- Describes the document -->
::Creator "Merchandising team"

## Product Categories
<!-- Describes the concept scheme -->
::scope note Categories shown on the storefront.

- Electronics
  <!-- Describes Electronics -->
  ::notation EL-01

  - Computers
    <!-- Describes Computers -->
    ::notation EL-02

Field values

A field's value can take any of these forms:

Folio
<!-- Text: type it as is, or put it in quotes -->
::scope note Categories shown on the storefront.
::preferred label "Computers"

<!-- Text in a specific language, with commas between several values -->
::alternative label "Gadgets"@en, "Geräte"@de

<!-- A date or other typed value -->
::Date Issued "2024-03-01"^^xsd:date

<!-- A whole number or a decimal -->
::min count 1
::max inclusive 0.35

<!-- A boolean: true or false -->
::closed true

Unquoted text runs to the end of the line, so a comma in it is part of the text, and it is English if the property takes text in a language. An unquoted 2024-03-01 is plain text, not a date; ^^ names an XSD datatype. A value can also be a link to an entity: see Entity links.

In Folio vs. the file

The Folio editor shows a field by its property's label, and the file stores the property's address. Both are the same field:

Folio
<!-- In Folio -->
::notation EL-01

<!-- In the file -->
::[](http://www.w3.org/2004/02/skos/core#notation) EL-01

Examples

Under the Taxonomy Map, a field on a list item adds statements about that concept, one per value:

Folio
- Electronics
  ::alternative label "Gadgets"@en, "Geräte"@de

The field adds this to the graph:

Turtle
:electronics skos:altLabel "Gadgets"@en ;
  skos:altLabel "Geräte"@de .

Under the Schema Map, the same syntax sets a rule on a property: every supplier has at least one country.

Folio
## Supplier

An outside organization that sells us raw materials.

### country

The country where the supplier is registered.
::name "Country"@en
::min count 1

In the graph, the Supplier class and its country property become:

Turtle
:Supplier a svs:ClassSchema ;
  rdfs:label "Supplier"@en ;
  rdfs:comment "An outside organization that sells us raw materials."@en ;
  sh:property <Supply%20Chain%20Model/.well-known/genid/markdown/Supplier-country> .

<Supply%20Chain%20Model/.well-known/genid/markdown/Supplier-country>
  a sh:PropertyShape ;
  sh:path :country ;
  sh:name "Country"@en ;
  sh:description "The country where the supplier is registered."@en ;
  sh:order 0.0 ;
  sh:minCount 1 .

A link to an entity is a CommonMark link to another entity in the workspace:

Folio
[](./document#entity)

To add a link, type [[ in a field's value or in body text and pick the entity from the list of entities in the workspace, and Folio inserts the link.

Where you put a link decides whether it adds to the graph.

Folio
- Laptops
  <!-- A field's value: relates Laptops to Computers -->
  ::has related Computers

  <!-- Body text: the link relates nothing -->
  Sold alongside Computers

The Folio editor shows a link by the entity's label, and the file stores the path to the entity. Both are the same link:

Folio
<!-- In Folio -->
Sold alongside Computers

<!-- In the file -->
Sold alongside [](./Product%20Catalog#computers)

In a sales document under the Taxonomy Map, a link as a field's value relates Laptops to Computers in the Product Catalog:

Folio
- Laptops
  ::has related Computers

The field adds this to the graph:

Turtle
:laptops skos:related
  <https://example.org/my-semantic-package/Product%20Catalog#computers> .

Mappings

A mapping decides what a document's headings and list items become in the graph. It is what makes one document a domain model and another a taxonomy: the syntax you type stays the same, and only the statements it builds change.

These are the mappings for Markdown documents:

None (default)

The default for any document is no mapping. Folio records its title and leaves the rest alone, and Graph View stays blank until you pick a mapping. Supplier onboarding.md has none:

Supplier onboarding.md
# Supplier onboarding

## Approval

Procurement signs off before the first order.

Note Map

Ordinary prose, where every heading below the title becomes a section of the document that other documents can link to. See Graph your Markdown for a walkthrough. Supplier review.md has two:

Supplier review.md
# Supplier review
::mappedBy Note Map

## Shortlist

Halden Components and Brightline Devices passed the first audit.

## Open questions

Lead times for computers from both suppliers.

Schema Map

Classes, their properties and the rules every entity must satisfy, written in RDFS and SHACL: each second-level heading is a class, and the headings under it are its properties. See Classes for what a class can hold, written in Turtle. Supply Chain Model.md declares one class:

Supply Chain Model.md
# Supply Chain Model
::mappedBy Schema Map

## Supplier

An outside organization that sells us raw materials.

### country

The country where the supplier is registered.
::name "Country"@en
::datatype string

Taxonomy Map

A tree of categories in SKOS: each second-level heading is a concept scheme, the list items under it are its concepts, and indenting an item places it under the one above. Under this mapping, Folio checks the document against the SKOS Taxonomy profile. See Taxonomies. Sales Regions.md places two countries under Europe:

Sales Regions.md
# Sales Regions
::mappedBy Taxonomy Map

## Regions

- Europe
  - Germany
  - France

Vocabulary Map

The same document as a taxonomy, but flat: indenting an item does not place it under another. See Taxonomies for how concepts work. Payment Terms.md lists three:

Payment Terms.md
# Payment Terms
::mappedBy Vocabulary Map

## Payment Terms

- Net 30
- Net 60
- Due on receipt

Working with mappings

Pick a mapping from the mapping selector at the top right of the Folio editor. Folio writes the ::mappedBy field under the title, and picking None (default) removes it. Both forms are the same field:

Folio
<!-- In Folio -->
::mappedBy Taxonomy Map

<!-- In the file -->
::[mappedBy](https://pkg.semvia.io/semvia/folio/mapping#mappedBy) [Taxonomy Map](https://pkg.semvia.io/semvia/folio/taxonomy-map#TaxonomyMap)

A mapping is itself a document of rules. Open mapping definition, the compass beside the mapping selector, opens it. Write your own in the workspace and point a document at it.

A mapping for CSV, Parquet or Excel files is written in Turtle as an RML mapping, not with the selector's RML Mapping Map: see Query CSV, Parquet and Excel files.