# Graph your Markdown

> Create two Markdown files in Folio, pick a mapping, and each becomes an entity in your workspace's graph. Add fields that link them, then query across the graph.

Source: https://semvia.io/docs/quickstart/graph-your-markdown

[Markdown](https://spec.commonmark.org/) 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](https://obsidian.md/), 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:

  ```folio
  # 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.

Figure: The Supplier brief file in Folio's editor with the mapping selector open at the top right. None (default) is checked, and the pointer is on Note Map, the next option, above RML Mapping Map, Schema Map, Taxonomy Map and Vocabulary Map.

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.

Figure: Supplier brief.md in the editor, with Note Map in the mapping selector and the mappedBy Note Map line under the title. Graph View on the right shows two Section nodes, Evaluation criteria and Shortlist, each with an Is Part Of row that reads Supplier brief.

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:

  ```folio
  # 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.

Figure: The new line under the mappedBy line reads ::Description. The field list shows Description first and highlighted, under Properties of MarkdownDocument, Note, with other description fields below it under Other properties.

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

> **In the file.** The editor shows `::Description`, but the file saves `::[Description](http://purl.org/dc/terms/description)`. The address is the standard property for a description, so any tool that reads the file knows what the field means.
>
> See [Markdown syntax](https://semvia.io/docs/authoring/markdown#fields) for every form a field can take.

## 6. Link two entities

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.

Figure: The Project Atlas file with a Relation field being typed. The value reads [[Supplier brief and the page list beneath it holds one entry, Supplier brief.

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.

Figure: Views open from the Activity Bar, beside Supplier brief.md. The list reads Packages, secrets, Problems and Terminal under Quick launch, and Graph View and New SPARQL Query under Everything else. Graph View is highlighted.

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

Figure: The Query panel beside the Graph View toolbar. Universe reads Workspace. The Blacklist lists six hidden items: conformsTo, Document, inScheme, isDefinedBy, mappedBy and seeAlso. The Document chip reads 2 nodes, and a green outline marks it.

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.

Figure: Graph View of the workspace. Supplier brief and Project Atlas are Markdown Document nodes, each listing Relation to the other file. Two edges labelled relation join them. Shortlist and Evaluation criteria have isPartOf edges to Supplier brief, and Goals and Risks have isPartOf edges to Project Atlas. A graph-your-markdown Semantic Package node sits at the top.

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](https://www.dublincore.org/specifications/dublin-core/dcmi-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](https://www.w3.org/TR/sparql11-query/), the standard query language for graphs:

  ```sparql
  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**.

Figure: The Results tab under the query, reading 4 rows. Columns file, section and relatedTo. Project Atlas, Goals, Supplier brief. Project Atlas, Risks, Supplier brief. Supplier brief, Evaluation criteria, Project Atlas. Supplier brief, Shortlist, Project Atlas.

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

[Next: Markdown syntax](https://semvia.io/docs/authoring/markdown): Every line Folio reads, and what each one builds in the graph.
