Writing documentation pages¶

The pages of a SHMARQL site are ordinary Markdown files in one folder, set with DOCS_PATH (default: docs). Edit a file, reload the page, and the change is there. No build step is needed.

Files and addresses¶

• Other files (images, PDFs, ZIPs, …) are served as they are, so ![Logo](images/logo.png) just works.
• Files and folders whose names start with . or _ are ignored.
• Links between Markdown files are rewritten to these addresses. Write [Profiles](../configuration/profiles.md) and readers get /configuration/profiles. The files stay readable on GitHub or in an editor too.

Titles and navigation¶

A page's title is the title: in its YAML front matter, or else its first # Heading:

---
title: Getting started
---

# Getting started

The navigation sidebar is built from the folder automatically: first the files of a folder, then its sub-folders, each sorted by file name. A sub-folder becomes a section titled after its index.md. A table of contents for the current page is generated from its headings.

Markdown features¶

Next to standard Markdown you can use tables, footnotes, definition lists, abbreviations, task lists, ~~strikethrough~~, attribute lists ({: .class }), Markdown inside HTML blocks, and syntax highlighting for code blocks. Blocks such as notes, warnings, collapsible details and tabs use the /// syntax of pymdown-extensions:

/// note | Wikidata is big
Use LIMIT while you explore.
///

/// details | Show the answer
It's `wd:Q41264`.
///

/// tab | SPARQL
`SELECT * WHERE { ?s ?p ?o } LIMIT 10`
///

/// tab | Python
`sparql.setQuery("SELECT * WHERE { ?s ?p ?o } LIMIT 10")`
///

That looks like this:

Example queries readers can run¶

A code block marked sparql gets a ▶ run link that opens the query in the query editor:

```sparql
SELECT ?museum ?museumLabel WHERE {
  ?painting wdt:P170 wd:Q41264 ; wdt:P195 ?museum .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}
```

SELECT ?museum ?museumLabel WHERE {
  ?painting wdt:P170 wd:Q41264 ; wdt:P195 ?museum .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}

Live results in a page¶

A code block marked shmarql is run when the page is shown, and the results table appears in its place. Add kg="<profile name>" to choose the profile, and title="…" for a caption:

```shmarql {title="Vermeer's paintings in the Mauritshuis" kg="wikidata"}
SELECT ?painting ?paintingLabel WHERE {
  ?painting wdt:P170 wd:Q41264 ; wdt:P195 wd:Q221092 .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}
```

A page with such a block is treated as a data story. That also allows the other kinds of Special Node: charts, maps, IIIF viewers and so on. See Data stories and the Markdown format.