Skip to content

Quickstart Graph your Markdown

New to Folio? Start here

Graph your Markdown

Markdown is one more source you bind into your workspace's graph, alongside the databases, JSON APIs and CSV, Parquet and Excel files in the other quickstarts. Each Markdown file becomes an entity, its headings become entities that are parts of it, and the fields you add on :: lines relate them. You query all of it as one graph.

This quickstart uses two Markdown files, Supplier brief.md and Project Atlas.md. If you're coming from Obsidian, your vault is a folder of Markdown files, so you open it as a workspace the same way. The first time, open a copy of your vault.

1. Create a file

  1. Select New file in the Explorer, pick Markdown and type Supplier brief as the name. Folio adds .md, so the file is Supplier brief.md.

  2. Paste this into it:

    Supplier brief.md
    # Supplier brief
    
    Suppliers on the shortlist for the Atlas conveyor contract.
    
    ## Shortlist
    
    - Halden Conveyor Systems
    - Brightline Robotics
    
    ## Evaluation criteria
    
    - Lead time under twelve weeks
    - Service engineers in every region

2. Open the Graph View

Right-click the Supplier brief.md tab and choose Split Right → Graph View. Graph View opens to the right of the editor and stays blank until you pick a mapping in the next step.

3. Pick a mapping

Click the mapping selector at the top right of the editor, which reads None (default), and pick Note Map. A mapping tells Folio how to read a file into the graph. Note Map reads a file's title, its headings and its :: lines.

Pick Note Map, under None (default).

Folio adds the ::mappedBy Note Map line under the title:

Folio
# Supplier brief
::mappedBy Note Map

Once a mapping is selected, Graph View draws a node for each ## heading, Shortlist and Evaluation criteria, and each node reads Is Part Of Supplier brief. The file is an entity named by its # title, and each heading is an entity that is part of it, so a query can reach a file's entity through its sections.

Each heading becomes a section that is part of Supplier brief.

4. Add a second file

Step 6 links two files, so create a second one. Project Atlas.md describes the project the supplier brief belongs to.

  1. Select New file in the Explorer, pick Markdown and type Project Atlas as the name.

  2. Paste this into it:

    Project Atlas.md
    # Project Atlas
    
    Automated picking and sorting for the regional distribution centres.
    
    ## Goals
    
    - Double sorting throughput by Q3
    
    ## Risks
    
    - Supplier lead times slip past the install window
  3. Pick Note Map in the mapping selector. Folio adds the ::mappedBy Note Map line under the title, and the selector reads Note Map.

5. Add a field

A :: line, called a field, states a fact about the entity.

  1. Open Supplier brief.md, start a new line under ::mappedBy Note Map and type ::. A list of fields opens, with the ones Note Map expects first.
With Description typed, Description is the highlighted field.
  1. Type Description and press Enter to pick it, then type a space and this value: Shortlist and criteria for the Atlas conveyor contract. The top of the file now reads:

    Folio
    # Supplier brief
    ::mappedBy Note Map
    ::Description Shortlist and criteria for the Atlas conveyor contract

A link is a field whose value is another entity. Here each file links to the other.

  1. Open Project Atlas.md, start a new line under ::mappedBy Note Map, type ::Relation and press Enter to pick it, then type a space and [[Supplier brief. A list of pages opens.
The page list shows Supplier brief.
  1. Press Enter to pick Supplier brief. The Relation line says Project Atlas relates to Supplier brief. The top of the file now reads:

    Folio
    # Project Atlas
    ::mappedBy Note Map
    ::Relation Supplier brief
  2. Now link Supplier brief back. In Supplier brief.md, start a new line under the ::Description line, type ::Relation and press Enter to pick it, then type a space and [[Project Atlas. Press Enter to pick Project Atlas. The top of the file now reads:

    Folio
    # Supplier brief
    ::mappedBy Note Map
    ::Description Shortlist and criteria for the Atlas conveyor contract
    ::Relation Project Atlas

7. See both files linked

The Graph View beside each file shows only that file. To see both files and the link between them, open a Graph View of the whole workspace.

  1. Click Views in the Activity Bar, then Graph View. Graph View opens as a new tab.
Graph View is under Everything else in Views.
  1. This Graph View covers the whole workspace but hides the files themselves. Click Query in the Graph View toolbar. Under Blacklist, click the ✕ on Document.
Document is on the Blacklist, so both files are hidden. The green outline marks the Document chip and its ✕.

Graph View now draws a node for Supplier brief and one for Project Atlas, each with its sections attached by isPartOf edges. The two Relation lines become two edges between the files, one each way, drawn crossing under a single relation label.

Both files, their sections and the Relation edges between them.

8. Query across the graph

A query asks the graph a question and gets back a table. This one asks: for each file, what are its sections, and which file does it relate to? It reads both files at once.

Note Map stores a file's title as dct:title, the link from a file to each section as dct:hasPart, and the Relation field as dct:relation, all Dublin Core terms. A section's name is its rdfs:label. The query asks for those four.

  1. Select New file in the Explorer, pick SPARQL Query and name the file Sections and links.rq.

  2. Replace the starter query with this query, written in SPARQL, the standard query language for graphs:

    Sections and links.rq
    PREFIX dct: <http://purl.org/dc/terms/>
    PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
    
    SELECT ?file ?section ?relatedTo
    WHERE {
      # each file by its title, and the name of every section its headings made
      ?entity dct:title ?file ;
              dct:hasPart/rdfs:label ?section .
      # the title of the file it relates to, left blank if it has no Relation line
      OPTIONAL { ?entity dct:relation/dct:title ?relatedTo }
    }
    # one row per section, grouped by file
    ORDER BY ?file ?section
  3. Click Run.

One row for each section of a file, with the file it relates to.