MkDocs

mkdocs-macros-sparqld is an mkdocs-macros pluglet. During mkdocs build or mkdocs serve it starts a read-only sparqld endpoint over a configured directory and expands SPARQL macros into the rendered pages.

This documentation site uses the pluglet for its live SPARQL examples.

Install

pip install mkdocs-macros-sparqld

Also install the sparqld binary and keep it on PATH unless you override extra.sparqld.binary below.

Required configuration

Register the pluglet with mkdocs-macros:

plugins:
  - macros:
      modules: [mkdocs_macros_sparqld]

Nothing else is required when sparqld is on PATH and the served tree is the project's docs/ directory.

Optional customization

Override defaults under extra.sparqld only when you need them:

extra:
  sparqld:
    directory: data                    # default: docs
    binary: target/debug/sparqld       # default: sparqld on PATH

Key	Default	When to set it
directory	docs	The RDF tree is not docs/ (for example data/)
binary	sparqld	The executable is not on PATH, or you want a project-local build such as target/debug/sparqld
## Macros and filters

sparql

Run a verbatim SPARQL query. A SELECT returns a list of binding dicts (one dict per row, keys are variable names).

{{ sparql('SELECT ?name WHERE { ?s <https://schema.org/name> ?name } LIMIT 3') | sparql_table }}

name
SPARQL cheat sheet
Named graphs
Query sparqld with SPARQLWrapper

stored_sparql

Run a .rq file whose path is relative to the MkDocs project root (the directory that contains mkdocs.yml).

{{ stored_sparql('docs/queries/names.rq') | sparql_table }}

graph	name
sparqld:examples/alpha-centauri.yamlld	Alpha Centauri
sparqld:examples/centaurus.md	Centaurus
sparqld:examples/proxima-centauri-b.jsonld	Proxima Centauri b

sparql_table filter

Render SELECT bindings as a Markdown table. Pipe the result of sparql or stored_sparql:

{{ stored_sparql('docs/queries/names.rq') | sparql_table }}

Programmatic helpers

A local MkDocs macros module can reuse the same endpoint:

from mkdocs_macros_sparqld import ensure_endpoint, run_query

endpoint = ensure_endpoint()
content_type, body = run_query('ASK { ?s ?p ?o }')