> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Linked Markdown

> Linked Markdown structures Markdown documents as semantic graph nodes.

Linked Markdown is a specification for Markdown documents with semantic
frontmatter. It lets ordinary Markdown pages carry typed JSON-LD-style
attributes that can be validated, queried, and loaded into RDF tooling such as
Wazoo [Worlds](/worlds/index).

## Example

```md theme={null}
---
{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
}
---

# Ethan Davidson

Ethan Davidson is a
[knowledge graph engineer](./roles/knowledge-graph-engineer.md).
```

## Markdown to JSON-LD

Before: a plain Markdown page with no machine-readable structure.

```md theme={null}
# Ethan Davidson

Ethan Davidson is a knowledge graph engineer.
```

After: the same content as a Linked Markdown document, where the frontmatter
block parses as JSON-LD.

```md theme={null}
---
{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
  "schema:jobTitle": "Knowledge graph engineer",
}
---

# Ethan Davidson

Ethan Davidson is a knowledge graph engineer.
```

The frontmatter parses directly into JSON-LD attributes via `extract`:

```json theme={null}
{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
  "schema:jobTitle": "Knowledge graph engineer"
}
```

## What it unlocks

* Markdown that remains pleasant for humans to write.
* Frontmatter that machines can interpret as semantic data.
* Compatibility with JSON-LD, RDFLib, and RDF graph workflows.
* Shared conformance tests across language implementations.

## Repositories

| Repository                                                            | Purpose                                                          |
| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [linked-markdown](https://github.com/wazootech/linked-markdown)       | Specification, paper, conformance suite, and community materials |
| [linked-markdown-ts](https://github.com/wazootech/linked-markdown-ts) | TypeScript implementation published on JSR                       |
| [linked-markdown-py](https://github.com/wazootech/linked-markdown-py) | Python implementation published on PyPI                          |

## Install

<CodeGroup>
  ```bash npm theme={null}
  npx jsr add @wazoo/linked-markdown
  ```

  ```bash deno theme={null}
  deno add jsr:@wazoo/linked-markdown
  ```

  ```bash pnpm theme={null}
  pnpm dlx jsr add @wazoo/linked-markdown
  ```

  ```bash yarn theme={null}
  yarn dlx jsr add @wazoo/linked-markdown
  ```

  ```bash bun theme={null}
  bunx jsr add @wazoo/linked-markdown
  ```

  ```bash python theme={null}
  pip install linked-markdown
  ```
</CodeGroup>

## Parse frontmatter

Use `extract` to read semantic attributes from a Markdown document:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { extract } from "@wazoo/linked-markdown";

  const result = extract(`---
  {
    "@id": "https://example.org/docs/alice",
    "@type": "schema:Person"
  }
  ---

  # Alice
  `);

  console.log(result.attrs);
  // { "@id": "https://example.org/docs/alice", "@type": "schema:Person" }
  ```

  ```python Python theme={null}
  from linked_markdown import extract

  result = extract("""---
  {
    "@id": "https://example.org/docs/alice",
    "@type": "schema:Person"
  }
  ---

  # Alice
  """)

  print(result.attrs)
  # {'@id': 'https://example.org/docs/alice', '@type': 'schema:Person'}
  ```
</CodeGroup>

## RDF compatibility

The `attrs` data returned by `extract()` is valid JSON-LD, ready for loading
into RDF graph stores:

<CodeGroup>
  ```python Python (RDFLib) theme={null}
  import json
  import rdflib
  from linked_markdown import extract

  result = extract(markdown)
  graph = rdflib.Graph()
  graph.parse(data=json.dumps(result.attrs), format="json-ld")
  ```

  ```typescript TypeScript (jsonld) theme={null}
  import jsonld from "jsonld";
  import { extract } from "@wazoo/linked-markdown";

  const result = extract(markdown);
  const quads = await jsonld.toRDF(result.attrs);
  // quads is an Array of RDF/JS quads, directly loadable into RDF quad stores
  ```
</CodeGroup>