diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
index 5d06dc51..79dacb3e 100644
--- a/.github/workflows/main.yaml
+++ b/.github/workflows/main.yaml
@@ -70,6 +70,7 @@ jobs:
         pytest tests/test_manifests.py --tests=./specifications/json-ld-framing/tests --loader=${{ matrix.loader }}
         pytest tests/test_manifests.py --tests=./specifications/normalization/tests --loader=${{ matrix.loader }}
         pytest tests/test_manifests.py --tests=./specifications/rdf-canon/tests --loader=${{ matrix.loader }}
+        pytest tests/test_manifests.py --tests=./specifications/yaml-ld/tests --loader=${{ matrix.loader }}
         pytest --ignore ./tests/test_manifests.py
       env:
         LOADER: ${{ matrix.loader }}
@@ -106,4 +107,4 @@ jobs:
         uses: MishaKav/pytest-coverage-comment@ae0e8a539a3f310aefb3bfb6a2209778a21fa42b
         with:
           pytest-coverage-path: ./pytest-coverage.txt
-          junitxml-path: ./pytest.xml
\ No newline at end of file
+          junitxml-path: ./pytest.xml
diff --git a/.gitignore b/.gitignore
index 820ee873..1bed7b5b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,9 @@ tests/data/test_caching.json
 
 # Local version file for pyenv
 .python-version
+
+# Local lock file for uv
+uv.lock
+
+# Codex CLI
+.codex
diff --git a/.gitmodules b/.gitmodules
index 87e7ce95..824bc216 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -10,3 +10,6 @@
 [submodule "specifications/rdf-canon"]
 	path = specifications/rdf-canon
 	url = https://github.com/w3c/rdf-canon.git
+[submodule "specifications/yaml-ld"]
+	path = specifications/yaml-ld
+	url = https://github.com/w3c/yaml-ld.git
diff --git a/AGENTS.md b/AGENTS.md
index fd178e3a..07063a07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,7 +29,7 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) for code style, linting (e.g. `make lint
 ### Documentation validation
 
 - **No in-repo Playwright.** Do not add `@playwright/test`, `playwright.config.js`, or e2e test dependencies. Live browser checks use **only** the Playwright MCP server (`user-playwright`).
-- After doc changes, run `make docs-build` (strict). For interactive checks, run `make docs-serve` and validate with Playwright MCP: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_wait_for`. Prefer `browser_run_code_unsafe` with `page.screenshot({ animations: 'disabled', timeout: 60000 })` over `browser_take_screenshot` (font load timeouts).
+- After doc changes, run `make docs-build` (strict). Before launching a preview server, first use Playwright MCP to check the configured local docs URL (normally `http://127.0.0.1:8000/pyld/`) and reuse it when it is responsive; run `make docs-serve` only when no responsive preview server is available. Validate interactive checks with Playwright MCP: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_wait_for`. Prefer `browser_run_code_unsafe` with `page.screenshot({ animations: 'disabled', timeout: 60000 })` over `browser_take_screenshot` (font load timeouts).
 
 ## Committing
 
diff --git a/README.md b/README.md
index fca45e7f..805f2f59 100644
--- a/README.md
+++ b/README.md
@@ -388,13 +388,14 @@ git submodule update
 #### Cloning manually
 
 You can also avoid using git submodules by manually cloning the `json-ld-api`,
-`json-ld-framing`, and `normalization` repositories hosted on GitHub using the
-following commands:
+`json-ld-framing`, `normalization`, and `yaml-ld` repositories hosted on GitHub
+using the following commands:
 
 ```bash
 git clone https://github.com/w3c/json-ld-api ./specifications/json-ld-api
 git clone https://github.com/w3c/json-ld-framing ./specifications/json-ld-framing
 git clone https://github.com/json-ld/normalization ./specifications/normalization
+git clone https://github.com/w3c/yaml-ld ./specifications/yaml-ld
 ```
 
 Note that you can clone these repositories into any location you wish; however,
diff --git a/docs/project/decisions/choose-where-to-host-yaml-ld-support/implement-yaml-ld-in-pyld.md b/docs/project/decisions/choose-where-to-host-yaml-ld-support/implement-yaml-ld-in-pyld.md
new file mode 100644
index 00000000..6e3b56ad
--- /dev/null
+++ b/docs/project/decisions/choose-where-to-host-yaml-ld-support/implement-yaml-ld-in-pyld.md
@@ -0,0 +1,112 @@
+# :material-package-variant: Implement YAML-LD in PyLD
+
+!!! info "Conditional roadmap"
+
+    This is the implementation universe in which [:fontawesome-brands-github: `digitalbazaar/pyld`](https://github.com/digitalbazaar/pyld) owns YAML-LD support. It applies only if the parent decision selects this alternative.
+
+## :material-target: Delivered contract
+
+`PyLD[yaml-ld]` adds YAML-LD document loading to the existing PyLD API; `PyLD[cli,yaml-ld]` adds that capability to the CLI. The implementation supports the YAML-LD JSON profile only: YAML 1.2 Core-schema values that produce JSON values. It does not implement the YAML-LD extended profile: `processingMode='yaml-ld-extended'`, or a profile token exactly `http://www.w3.org/ns/json-ld#extended`, fails with `jsonld.LoadDocumentError`, code `profile-error`. Ignore unknown profile tokens; do not reject an arbitrary `profile` parameter. YAML tags outside the Core schema are discarded when constructing the JSON representation, as required by the JSON profile. A missing `ruamel.yaml` import fails only when a YAML document is actually parsed, with an actionable `yaml-ld` extra message.
+
+Raw YAML `str` and `bytes` are not new public inputs to `expand`, `compact`, `flatten`, `frame`, `to_rdf`, or `normalize`: a string remains a document URL and a mapping/list remains an already-parsed JSON-compatible document. YAML enters those APIs through a document URL and its document loader. `from_rdf` remains raw RDF input only.
+
+Do not add `pyld.yaml_ld.expand()` or sibling transformation functions. A
+`pyld.yaml_ld` namespace may expose parsing helpers such as `loads()` and
+`loads_all()`, while `pyld.jsonld.*` remains the sole transformation API.
+
+## :material-source-branch: Implementation baseline
+
+Build this work on [:fontawesome-brands-github: `306-complete-pyld-cli`](https://github.com/digitalbazaar/pyld/tree/306-complete-pyld-cli), which adds [`lib/pyld/cli/input.py`](https://github.com/digitalbazaar/pyld/blob/306-complete-pyld-cli/lib/pyld/cli/input.py) and the command test contract. Either rebase after that branch merges, or create this as a stacked PR with `306-complete-pyld-cli` as its base. Do not reimplement the CLI in this change.
+
+## :material-clipboard-check-outline: Architectural decisions
+
+### One media parser at the PyLD loading boundary
+
+Add `lib/pyld/documentloader/media.py`, with a single idempotent entry point used by [`jsonld.load_document`](https://github.com/digitalbazaar/pyld/blob/master/lib/pyld/jsonld.py): `parse_remote_document(remote_doc, options, profile) -> RemoteDocument`.
+
+1. Normalize `contentType` by lowercasing the media type and removing parameters for dispatch, while retaining the parameter map to inspect `profile`. Recognize `application/ld+yaml`, `application/yaml`, `application/x-yaml`, and `*+yaml`; recognize JSON as `application/ld+json`, `application/json`, and `*+json`; retain the existing HTML types.
+2. If `remote_doc['document']` is a mapping or list, return it unchanged. This makes the boundary idempotent and keeps custom loaders which already return parsed JSON compatible.
+3. Built-in loaders always supply raw bytes. A custom loader may supply text, which the boundary first encodes as UTF-8 and then decodes using the same optional-BOM path; an unencodable string or malformed byte sequence is `invalid-encoding`. Any other value is a `loading document failed` error. Dispatch YAML and JSON to the media parser; dispatch HTML to the PyLD HTML folding algorithm below. The parser replaces `remote_doc['document']` with only ordinary Python `dict`, `list`, `str`, `int`, `float`, `bool`, or `None` values.
+4. Call this helper exactly once, immediately after `options['documentLoader'](url, options)` in `load_document`, before the null-document check and before processing API code observes the result. It owns parsing, HTML traversal, base handling, profile selection, and fragment selection. Built-in and custom loader output therefore follows the same path.
+
+Change [`FileDocumentLoader`](https://github.com/digitalbazaar/pyld/blob/master/lib/pyld/documentloader/file.py), [`RequestsDocumentLoader`](https://github.com/digitalbazaar/pyld/blob/master/lib/pyld/documentloader/requests.py), and [`AioHttpDocumentLoader`](https://github.com/digitalbazaar/pyld/blob/master/lib/pyld/documentloader/aiohttp.py) to return raw bytes in `document`, plus `contentType`, `contextUrl`, and final `documentUrl`. In particular, replace Requests’ `response.json()` and aiohttp’s `response.json(content_type=None)` with raw-body reads. `SqliteCacheRequestsDocumentLoader` continues to inherit the Requests behavior. Do not change the documented `RemoteDocument` fields or require third-party loaders to change: their parsed mapping/list output is the idempotent case.
+
+### YAML parsing and errors
+
+Use `ruamel.yaml >=0.19`, configured for YAML 1.2 and the Core schema. Decode once, safely compose/load every document in a stream, and recursively convert it to JSON values: keys must be strings; aliases are copied; undefined aliases and cyclic aliases fail; `.inf` and `.nan` are rejected because they are not JSON numbers. A top-level scalar fails and an empty stream fails. With `extractAllScripts=False`, a YAML stream returns its first document; with `extractAllScripts=True`, it returns an array of all stream documents, including an array of one document. This rule applies equally to direct YAML and YAML script bodies.
+
+Production errors use the current YAML-LD vocabulary: decode errors are `invalid-encoding`; non-string mapping keys are `mapping-key-error`; and the extended profile is `profile-error`. Syntax errors, scalar roots, empty streams, undefined/cyclic aliases, non-JSON floats, and unsupported document shapes are `loading document failed`. JSON is parsed only by the JSON dispatch branch and YAML only by YAML dispatch: do not describe or implement a “valid JSON but invalid YAML” fallback.
+
+### HTTP, files, links, and negotiation
+
+Extend `CONTENT_TYPES` with `.yamlld` → `application/ld+yaml` and `.yaml` → `application/yaml`. The exact default `Accept` header, unless the caller supplied `options['headers']`, is:
+
+```text
+application/ld+yaml, application/ld+json;q=0.9, application/yaml;q=0.8, application/x-yaml;q=0.8, application/json;q=0.7, text/html;q=0.5, application/xhtml+xml;q=0.5
+```
+
+This intentional YAML-first ordering implements the YAML-LD alternative’s preference; test the literal value in both HTTP loaders. When `requestProfile` is set, prepend the RFC-quoted `application/ld+json;profile="<requestProfile>", `, preserving the remaining order.
+
+Normalize a response `Content-Type` before link decisions. Continue to reject multiple JSON-LD context links. A `rel=alternate` is followed only if its normalized `type` is a supported YAML or JSON media type and the response is neither a supported YAML nor JSON media type; resolve it against the original request URL and recurse through the same loader with the same options. A context link is retained only when the response is neither `application/ld+json` nor `application/ld+yaml`; do not synthesize a context link from a YAML document. Preserve final URLs, redirect behavior, secure-mode enforcement, supplied headers, cache keys, and cache hit/miss behavior.
+
+### HTML folding, owned by PyLD
+
+`parse_remote_document` calls a refactored `load_html` that takes the raw HTML text, `documentUrl`, `profile`, and `options`; no transport loader parses HTML or script bodies.
+
+1. Parse HTML and resolve the first `<base href>` against `options['base']` or `documentUrl`; store the resolved base in `options['base']` and replace the remote document URL as current `load_document` does.
+2. If `documentUrl` has a fragment, select exactly the script whose `id` equals that fragment. It must have a supported JSON or YAML media type; otherwise raise `loading document failed`. Ignore `extractAllScripts` in this case and return only that script’s parsed document(s).
+3. Otherwise select `<script>` elements in document order whose normalized `type` is supported JSON or YAML. When a JSON `profile` argument is supplied, first select only `application/ld+json` scripts with the same profile parameter; if none match, select all supported scripts. Ignore unknown profile tokens. A YAML script carrying `http://www.w3.org/ns/json-ld#extended`, or an options processing mode of `yaml-ld-extended`, is `profile-error`; other YAML profile tokens are ignored.
+4. For each selected script, read its text without manually dedenting it, use its normalized type to invoke the same JSON/YAML parser, and retain each resulting mapping/list. A YAML stream contributes its documents in stream order.
+5. With `extractAllScripts=True`, flatten script and YAML-stream documents in source order to one list. Otherwise return the first parsed document. No selected script is `loading document failed`; a parse failure in a selected script is `invalid script element`, wrapping the canonical YAML/JSON cause.
+
+Test indentation, whitespace, JSON/YAML interleaving, profiles, fragment selection, a single and a multi-document YAML stream, and HTML base replacement.
+
+## :material-file-code-outline: Ordered implementation
+
+### 1. Package and expose the capability
+
+- [ ] Add `yaml-ld: ['ruamel.yaml>=0.19']` to `extras_require` in [`setup.py`](https://github.com/digitalbazaar/pyld/blob/306-complete-pyld-cli/setup.py). Add the CLI extra already defined by the baseline so `PyLD[cli,yaml-ld]` installs both groups; do not claim that extras conditionally create console scripts.
+- [ ] Add the parser module to the `pyld.documentloader` package and export only any intentionally public media constants/helpers from its package `__init__`; keep parsing functions internal otherwise.
+- [ ] Add `ruamel.yaml` to test dependencies and CI installation. Test installation/import without the extra, with `yaml-ld`, and with `cli,yaml-ld`.
+
+### 2. Change loader transport and central parsing
+
+- [ ] Implement the parser, then refactor `load_document`, built-in loaders, and SQLite-cache tests according to the single-boundary contract above.
+- [ ] Add unit tests for a custom `DocumentLoader` returning raw YAML text/bytes and a pre-parsed mapping. The former is parsed centrally and the latter stays unchanged.
+- [ ] Preserve `FileDocumentLoader` root confinement and Path/file-URL behavior. Preserve Requests/AioHTTP URL validation, sessions, TLS/secure mode, redirects, caller headers, alternate-link recursion, context-link errors, and cached raw response behavior.
+
+### 3. Preserve API contracts
+
+- [ ] Route URL input to `expand`, `compact`, `flatten`, `frame`, `to_rdf`, and URL-input `normalize` through `load_document`; retain dict/list behavior and all existing option defaults, including `processingMode` and omitted tri-state CLI-derived values.
+- [ ] Leave `from_rdf` and `inputFormat` behavior unchanged. Add API parity fixtures that compare a YAML URL with an equivalent JSON-LD URL for expand, compact, flatten, frame, `to_rdf`, and URL-based normalize.
+
+### 4. Make stdin format explicit in the CLI
+
+- [ ] Add `--stdin-format {json,yaml}` to the primary input commands `get`, `expand`, `compact`, `flatten`, `frame`, and `to-rdf`. It defaults to `json`, preserving the baseline CLI behavior. Reject it when `INPUT` is not `-`; reject values other than the two enum values through Typer validation. `--stdin-format yaml` calls the YAML parser directly and requires the extra; there is no content sniffing or JSON-to-YAML fallback.
+- [ ] Keep primary paths and HTTP(S) URLs as `document_url()` values. They must flow through `load_document` so final URL, base IRI, Content-Type, cache, secure mode, redirects, and custom CLI loader policy survive.
+- [ ] Implement `JSONOnlyOperand`: for `-`, it yields `json.load(sys.stdin)`; otherwise it yields the canonical source URL from `document_url()`. Pass that URL, not an eagerly parsed dict, as `CONTEXT`, `FRAME`, `--context`, or `--expand-context` to the processing operation.
+- [ ] Add `RestrictDesignatedUrlsToJson(delegate, designated_urls)` as the operation’s document-loader view. It delegates every URL through the configured file/remote/cache/security/header policy. Only when the requested URL is one of those explicit secondary source URLs does it normalize the returned `RemoteDocument` content type and reject YAML, HTML, and unsupported types; it returns the complete, unchanged `RemoteDocument` so `load_document` preserves `documentUrl`, `contextUrl`, and base metadata. Primary documents and nested contexts remain unrestricted. Contexts, frames, and expand contexts deliberately have no YAML format option.
+- [ ] Before installing that view, canonicalize a non-stdin primary `INPUT` with `document_url()` and reject the invocation with `typer.BadParameter('INPUT must not name the same URL as a JSON-only operand.')` when it equals a designated secondary URL. Without this check the view cannot distinguish a primary fetch from an explicitly JSON-only secondary fetch of the same URL. Test this error for local paths and HTTP URLs.
+- [ ] Retain `ensure_single_stdin()` across all primary and secondary operands. Retain raw RDF boundaries: `from-rdf` accepts only local N-Quads or `-` via `read_nquads`; `to-rdf` emits exactly `print_nquads()` → `sys.stdout.write()`, with no Rich formatting, added newline, escaping, or YAML serialization.
+- [ ] Keep JSON-LD 1.1-only. The top-level handler converts parser and loader failures to concise errors unless `--traceback` is passed.
+
+### 5. Complete the YAML-LD conformance runner
+
+Retain and pin the repository’s existing `specifications/yaml-ld` submodule revision [`af4c9c8eb77454645a0b16e69ec16b28a322ff06`](https://github.com/w3c/yaml-ld/commit/af4c9c8eb77454645a0b16e69ec16b28a322ff06) (`Add Introduction bridge paragraph`), and record that hash in the implementation PR description. Its `tests/manifest.jsonld` entry `#cr-utf8-2-negative` uses the legacy expected value `invalid encoding`, while its specification enum uses `invalid-encoding`. Production and direct unit tests use `invalid-encoding`; in `tests/runtests.py`, normalize **only that YAML-LD manifest expectation** `invalid encoding` to `invalid-encoding` before comparing `JsonLdError.code`. Do not alter expected error strings for other suites. Modify [`tests/runtests.py`](https://github.com/digitalbazaar/pyld/blob/master/tests/runtests.py) as follows:
+
+- [ ] In `read_test_property`, load `.yamlld` and `.yaml` expected, context, frame, and option files through the new media parser rather than `read_file`; retain `read_json` for JSON. Make `create_test_options` similarly parse YAML `expandContext` and preserve `extractAllScripts` supplied by a manifest.
+- [ ] In `load_locally`, recognize `.yamlld` and `.yaml`, retain fragments in `documentUrl`, return raw body plus normalized metadata, and let `jsonld.load_document` perform parsing. Apply manifest `contentType`, `httpLink`, `httpStatus`, and `redirectTo` before parsing; use the same normalized YAML/JSON alternate and context-link rules as production.
+- [ ] Delete YAML-primary-document `idRegex` skips: `compact-local-json-ld-context`, `cir-*`, `cr-*`, `aa-*`, `html-and-yaml-streams`, `html-dedent-*`, `*-documents-from-stream`, `local-json-ld-context`, `core-*`, `flatten`, `frame-t0001`, and the YAML-primary-document `to-rdf` skips. Retain, with an explicit `YAML context operands are outside this universe` comment, `compact-local-yaml-ld-context` and `local-yaml-ld-context`; do not claim zero skips for the whole suite. `#mixed-script-types` is not present at the pinned revision.
+- [ ] Run the pinned suite’s selected JSON-profile/YAML-primary-document set with `pytest tests/test_manifests.py --tests=./specifications/yaml-ld/tests --loader=requests` and again with `--loader=aiohttp`, excluding only the two retained YAML-context fixture identifiers above, on every current workflow matrix member (CPython 3.10–3.14 and PyPy 3.10/3.11). Update [`.github/workflows/main.yaml`](https://github.com/digitalbazaar/pyld/blob/master/.github/workflows/main.yaml) so the YAML dependency is installed before those commands.
+
+## :material-test-tube: Acceptance checklist
+
+- [ ] Parser tests cover UTF-8/BOM and exact `invalid-encoding`, Core values, non-Core tags, extended-profile rejection and ignored unknown profile tokens, string-key enforcement, scalar/empty roots, syntax/decode errors, aliases/undefined aliases/cycles, `.inf`/`.nan`, and YAML streams under both `extractAllScripts` values.
+- [ ] Loader tests cover each supported MIME type with parameters and `+yaml`, both extensions, exact Accept headers, YAML/JSON alternate links, context links, redirects, cache behavior, final/base URLs, secure failures, and custom raw/preparsed loaders.
+- [ ] HTML tests cover source ordering, mixed scripts, base, fragments, profiles, whitespace/indentation, and streams with both values of `extractAllScripts`.
+- [ ] CLI tests cover every primary command’s JSON stdin default and YAML `--stdin-format yaml`, invalid/misplaced option errors, no sniffing, primary YAML with each JSON URL secondary operand, rejected YAML explicit secondary URLs, same-primary/same-secondary URL rejection, JSON stdin secondary operands, one-stdin rejection, and missing-extra diagnostics.
+- [ ] Existing raw N-Quads exact-output, empty-output, remote-`from-rdf` rejection, option-default, and no-traceback tests stay green.
+- [ ] Run focused parser/loader/API/CLI tests, the full manifest matrix, `make lint`, and strict `make docs-build`; validate the rendered documentation in Chromium.
+
+??? info "Decisions"
+    This conditional roadmap supports [Implement YAML-LD support in …](index.md). It is not an adopted implementation plan until that ADR selects this alternative.
diff --git a/docs/project/decisions/choose-where-to-host-yaml-ld-support/index.md b/docs/project/decisions/choose-where-to-host-yaml-ld-support/index.md
new file mode 100644
index 00000000..888ce96c
--- /dev/null
+++ b/docs/project/decisions/choose-where-to-host-yaml-ld-support/index.md
@@ -0,0 +1,71 @@
+---
+title: Implement YAML-LD support in …
+status: undecided
+date: 2026-09-01
+author: Anatoly Scherbakov
+tags: [decision]
+hide: [toc]
+prerequisite:
+  title: Use `pyld.jsonld.expand()` for YAML-LD expansion
+  url: /pyld/project/decisions/use-pyld-jsonld-expand-for-yaml-ld/
+---
+
+# Implement YAML-LD support in …
+
+{{ adr_metadata(date, status, prerequisite) }}
+
+## :material-text-box-outline: Context
+
+This ADR compares the possible Python packaging homes for a YAML-LD implementation.
+
+### Requirements
+
+- [x] PyLD's `pyld` command is the sole callable YAML-LD CLI; do not introduce or retain a separate `yaml-ld` command.
+- [x] Require no backwards compatibility with the existing `python-yaml-ld` API, CLI, or package behavior. The selected universe may redesign or remove those surfaces to satisfy the PyLD-owned interface constraint.
+
+## :material-arrow-decision-outline: Decision
+
+<table data-adr-comparison markdown="1">
+  <tr markdown="span">
+    <th>Alternative</th>
+    <th>[PyLD implements YAML-LD](implement-yaml-ld-in-pyld.md)<br>[:fontawesome-brands-github: `digitalbazaar/pyld`](https://github.com/digitalbazaar/pyld)</th>
+    <th>[PyLD uses a parser-only YAML-LD adapter](provide-yaml-ld-through-a-pyld-facade.md)<br>[:fontawesome-brands-github: `digitalbazaar/pyld`](https://github.com/digitalbazaar/pyld) + [:fontawesome-brands-github: `iolanta-tech/yaml-ld-adapter`](https://github.com/iolanta-tech/yaml-ld-adapter)</th>
+  </tr>
+  <tr markdown="span">
+    <th>Install</th>
+    <td>Proposed `pyld[yaml-ld]` extra</td>
+    <td>Proposed `pyld[yaml-ld]` extra</td>
+  </tr>
+  <tr markdown="span">
+    <th>Dependencies</th>
+    <td>Proposed direct `ruamel.yaml ⩾0.19` dependency</td>
+    <td>Proposed `yaml-ld-adapter` dependency</td>
+  </tr>
+  <tr markdown="span">
+    <th>Test suite</th>
+    <td>PyLD CI [:fontawesome-brands-github: `main.yaml`](https://github.com/digitalbazaar/pyld/blob/6f29288adf241a72a49897787430c69752bf95d7/.github/workflows/main.yaml#L72) runs `specifications/yaml-ld/tests`</td>
+    <td>PyLD owns JSON-LD operation/conformance coverage; `yaml-ld-adapter` owns parser fixtures</td>
+  </tr>
+  <tr markdown="span">
+    <th>YAML parsing</th>
+    <td>Proposed PyLD-owned parser integration</td>
+    <td>Proposed use of its YAML parser adapter</td>
+  </tr>
+  <tr markdown="span">
+    <th>Decision</th>
+    <td></td>
+    <td></td>
+  </tr>
+</table>
+
+## :material-arrow-right-bold-outline: Consequences
+
+- Docs, optional extras, and ownership of YAML-LD conformance must match the chosen packaging home.
+- Dependency surface (YAML parser and any optional extras) will either grow in PyLD or stay in a separate package.
+- Release cadence for YAML-LD support fixes will either couple to PyLD releases or remain with a separate package.
+
+#### Implementation Steps
+
+- [ ] Record the Decision row outcome in this ADR (flip status to decided)
+- [ ] Align suite location, YAML parsing ownership, and install surface with the chosen column
+- [ ] Update project index / user docs if needed
diff --git a/docs/project/decisions/choose-where-to-host-yaml-ld-support/provide-yaml-ld-through-a-pyld-facade.md b/docs/project/decisions/choose-where-to-host-yaml-ld-support/provide-yaml-ld-through-a-pyld-facade.md
new file mode 100644
index 00000000..d0eab011
--- /dev/null
+++ b/docs/project/decisions/choose-where-to-host-yaml-ld-support/provide-yaml-ld-through-a-pyld-facade.md
@@ -0,0 +1,93 @@
+# :material-transit-connection-variant: Provide YAML-LD through a PyLD façade
+
+!!! info "Conditional roadmap"
+
+    This is the implementation universe in which [:fontawesome-brands-github: `digitalbazaar/pyld`](https://github.com/digitalbazaar/pyld) presents YAML-LD through an adapter extracted from [:fontawesome-brands-github: `iolanta-tech/python-yaml-ld`](https://github.com/iolanta-tech/python-yaml-ld). It applies only if the parent decision selects this alternative.
+
+## :material-target: Target experience
+
+Users install `PyLD[cli,yaml-ld]` and use the existing PyLD operations and the single `pyld` command. The optional PyLD extra installs the small `yaml-ld-adapter` distribution, not the `yaml-ld` high-level wrappers. Before the façade is released, remove the original package's high-level transformation wrappers, CLI modules, and conflicting `pyld` entry point; its migration guidance directs users to PyLD's `pyld` command and `pyld.jsonld.*` API.
+
+Build this work on [`306-complete-pyld-cli`](https://github.com/digitalbazaar/pyld/tree/306-complete-pyld-cli): either rebase after that branch merges, or submit this work as a PR stacked on it. That branch supplies the command modules, CLI cache, and class-based loaders on which this roadmap relies.
+
+## :material-clipboard-check-outline: Fixed implementation decisions
+
+### Adapter release contract
+
+- [ ] Create [:fontawesome-brands-github: `iolanta-tech/yaml-ld-adapter`](https://github.com/iolanta-tech/yaml-ld-adapter) as a `src/`-layout package: distribution `yaml-ld-adapter`, import package `yaml_ld_adapter`, source directory `src/yaml_ld_adapter/`, and tests in `tests/`.
+- [ ] Publish `yaml-ld-adapter` `1.0.0` before changing PyLD. Its runtime dependency is `ruamel.yaml>=0.19,<1`; its supported runtimes are PyLD's current matrix: CPython 3.10, 3.11, 3.12, 3.13, and 3.14, plus PyPy 3.10 and 3.11. Test the adapter on every member of that matrix before release.
+- [ ] Give the adapter exactly this public surface, with `JSONValue` recursively meaning `None | bool | int | float | str | list[JSONValue] | dict[str, JSONValue]` and `JSONDocument` meaning `dict[str, JSONValue] | list[JSONValue]`:
+
+    ```python
+    class YamlLdAdapterError(Exception):
+        code: Literal[
+            'invalid-encoding',
+            'mapping-key-error',
+            'loading-document-failed',
+            'profile-error',
+        ]
+
+    def parse_yaml_ld_stream(
+        data: bytes | str,
+        *,
+        source_url: str,
+        profile: str | None = None,
+    ) -> tuple[JSONDocument, ...]: ...
+    ```
+
+    The adapter accepts only raw YAML-LD and returns every document in a YAML stream; it performs no I/O, HTTP negotiation, HTML traversal, JSON-LD processing, caching, or CLI work.
+
+- [ ] Implement the YAML-LD Basic profile only. The adapter receives either `None` or the recognized `http://www.w3.org/ns/json-ld#extended` profile URI, and rejects the latter with `YamlLdAdapterError(code='profile-error')`. The PyLD media and HTML layers tokenize a space-separated `profile` parameter into URI tokens, ignore unknown tokens, and pass the recognized Extended URI to the adapter. This makes YAML tags and other Extended-profile features unsupported, rather than silently treating them as Basic YAML-LD. The [YAML-LD specification](https://w3c.github.io/yaml-ld/#application-ld-yaml) defines that profile parameter and identifies the Extended profile separately.
+- [ ] Parse UTF-8 or UTF-8 with a BOM using YAML 1.2 Core-schema rules. Preserve date-like scalars as strings; require string mapping keys; deep-copy aliases into a JSON tree; reject undefined aliases, cycles, scalar roots, empty streams, non-finite numbers, syntax failures, and non-UTF-8 input. Map those failures to the four adapter codes above. The current `python-yaml-ld` parser and its [`ruamel.yaml`](https://pypi.org/project/ruamel.yaml/) Core-schema configuration are the porting source; the YAML-LD specification requires YAML 1.2-compatible processing and JSON-compatible mapping keys.
+
+### PyLD media boundary and ownership
+
+- [ ] Add `pyld.documentloader.media.coerce_remote_document(remote_document, *, options, profile)` and make [`jsonld.load_document`](https://github.com/digitalbazaar/pyld/blob/306-complete-pyld-cli/lib/pyld/jsonld.py) call it exactly once after *every* built-in or user-supplied `documentLoader` returns **and after** its existing `base` override has set `remote_document['documentUrl']`. This ordering gives HTML parsing the final document URL. It returns a `RemoteDocument` with a parsed `document`; a dict or list is returned unchanged, making the step idempotent for custom loaders that already parse JSON.
+- [ ] Change `FileDocumentLoader`, `RequestsDocumentLoader`, and `AioHttpDocumentLoader` to return raw `bytes` plus `contentType`, `documentUrl`, and `contextUrl`. Do not call `response.json()` in transport loaders. `SqliteCacheRequestsDocumentLoader` continues to cache the raw HTTP response through its Requests delegate; parsing happens after a cache hit or miss through `coerce_remote_document`.
+- [ ] In `coerce_remote_document`, parse and normalize a Content-Type case-insensitively before stripping its parameters; retain the original `RemoteDocument['contentType']` value for callers. Use `json.loads` for JSON and `yaml_ld_adapter.parse_yaml_ld_stream` for `application/ld+yaml`, explicit HTTP/custom `application/yaml` or `application/x-yaml`, and registered `+yaml` types. For direct YAML, `extractAllScripts=False` selects the first YAML document and `True` returns a top-level array of every document, including a one-document stream; an empty stream is `loading document failed`. Recognize both `.yamlld` and `.yaml` as the canonical `application/ld+yaml` in `FileDocumentLoader`.
+- [ ] Normalize Content-Type and typed Link-header `alternate` parameters before applying the existing JSON-LD Link-header rules, while preserving the raw header values. Recognize a typed alternate with a supported YAML media type as dereferenceable alongside JSON-LD. Test Content-Type parameters, redirects, `secure=True`, cache hits, link contexts, and alternates with both raw built-in responses and a custom `DocumentLoader` returning `str` or `bytes`.
+- [ ] Change the default Accept header to this exact YAML-first order:
+
+    ```text
+    application/ld+yaml, application/ld+json;q=0.9, application/json;q=0.8, text/html;q=0.5, application/xhtml+xml;q=0.5
+    ```
+
+    Do not send an Extended-profile parameter because it is unsupported. Test that Requests and AioHTTP receive that exact header unless an API caller supplies `options['headers']`.
+
+### HTML is PyLD's responsibility
+
+- [ ] Keep HTML traversal in PyLD's `load_html`, which owns HTML `<base>` resolution, `documentUrl`, JSON-LD profile selection, fragment lookup, and the `options['base']` update. For every selected script, normalize its `type` and tokenize its space-separated profile parameter with the same rules as an HTTP Content-Type; parse JSON-LD scripts with `json.loads` and YAML-LD scripts with the adapter. Pass each YAML script's source text unchanged to the adapter: indentation and whitespace are significant YAML input.
+- [ ] With a fragment, select the named script only and reject a missing script or an unsupported script type as `loading document failed`. Without a fragment, `extractAllScripts=False` uses the first supported JSON-LD or YAML-LD script in source order. With `extractAllScripts=True`, process every supported script in source order.
+- [ ] Fold an all-scripts result deterministically: a JSON-LD array contributes its members; each YAML stream contributes its YAML documents in stream order; a mapping contributes itself. Thus a YAML stream in one HTML script behaves as separate scripts while mixed JSON/YAML scripts preserve document order. Add fixtures for mixed types, both indentation cases, fragments, HTML `<base>`, YAML streams, and `extractAllScripts` true and false.
+- [ ] Convert `YamlLdAdapterError` only in the PyLD media boundary: retain `invalid-encoding`, `mapping-key-error`, and `profile-error` as `JsonLdError.code`; map every other adapter parser failure to `loading document failed`. An HTML YAML-script failure is `invalid script element` with the adapter code in the error details. Do not expose adapter exceptions from PyLD.
+
+### CLI format and secondary-operand contract
+
+- [ ] Add `--input-format {json,yaml}` to the primary `INPUT` of `get`, `expand`, `compact`, `flatten`, `frame`, and `to-rdf`. It is required exactly when `INPUT` is `-` and rejected for a path or HTTP(S) URL. `json` calls `json.load`; `yaml` passes stdin bytes to the adapter. There is no format sniffing. `from-rdf` keeps its existing raw N-Quads stdin reader and has no `--input-format`.
+- [ ] Keep `CONTEXT`, `FRAME`, `--context`, and `--expand-context` JSON-only. They intentionally receive no YAML-format option. Their `-` form is JSON only and continues to participate in `ensure_single_stdin`.
+- [ ] Add `JsonOnlyOperandReader` in `pyld.cli.input`. For local paths and HTTP(S) URLs it calls the configured PyLD file/Requests/AioHTTP transport, cache, URL validation, redirect handling, and secure-mode checks, then parses only JSON. It returns a `RemoteDocument` retaining `contentType`, `contextUrl`, and final `documentUrl`; it rejects YAML and HTML before the general media boundary runs.
+- [ ] Add a `JsonOnlyOperandDocumentLoader` view around the configured loader. It serves that pre-read `RemoteDocument` when the processor dereferences the matching secondary URL, then delegates all other URLs to the regular loader. Pass the original canonical URL plus this view into `compact`, `frame`, `expand`, and `flatten`, so remote-context and relative-IRI semantics retain the pre-read document's final URL. For stdin, pass the parsed JSON value directly because it has no dereferenceable document URL.
+- [ ] Preserve PR #330's raw RDF boundary: `from-rdf` accepts only a local path or stdin as N-Quads; `to-rdf` accepts JSON or YAML primary input but writes exact N-Quads with `sys.stdout.write()` and never serializes YAML. Keep the concise CLI error handler unless `--traceback` is requested. Its package-install diagnostic must distinguish missing CLI dependencies (`PyLD[cli]`) from a YAML adapter requested by YAML input (`PyLD[cli,yaml-ld]`).
+
+## :material-map: Ordered implementation and verification
+
+### Release the adapter first
+
+- [ ] Extract the Core-schema parser from `python-yaml-ld` into `yaml-ld-adapter`; remove the high-level transformation wrappers, CLI modules, and conflicting `pyld` entry point, and publish a migration guide to PyLD's `pyld` command and `pyld.jsonld.*` API.
+- [ ] Add unit tests for every adapter signature and error code, byte/text parity, BOM, streams, aliases and cycles, mapping keys, scalar roots, non-finite floats, and Basic-profile tags. Run them on the declared CPython and PyPy matrix and build/test both sdist and wheel.
+- [ ] Release `yaml-ld-adapter==1.0.0`. Only after it is available, add `yaml-ld-adapter>=1.0.0,<2.0.0` to PyLD's `setup.py` `yaml-ld` extra; `cli` remains an independent extra. A JSON-only PyLD install must neither import `yaml_ld_adapter` nor depend on `ruamel.yaml`.
+
+### Add the façade in PyLD
+
+- [ ] Implement the raw-transport change and the single `coerce_remote_document` call site before adding YAML parsing. Add PyLD `documentloader.media` tests for Content-Type and Link-alternate normalization, profile token handling, direct YAML stream selection, and empty streams. Prove existing JSON, custom-loader, HTTP cache, Link-header, redirect, base-IRI, and secure-mode tests are unchanged.
+- [ ] Implement direct YAML media parsing, then HTML YAML-script parsing, then the JSON-only CLI reader/view and `--input-format` option. Add command-level tests for every command accepting primary stdin in each format, missing/invalid `--input-format`, JSON-only secondary stdin, multiple `-` rejection, local/remote JSON contexts and frames, raw N-Quads input/output, and no Rich styling in N-Quads output.
+- [ ] Add `yaml-ld-adapter` to CI's YAML-LD test environment and update `tests/runtests.py`: initialize the `specifications/yaml-ld` submodule, infer `.yamlld` and `.yaml` as `application/ld+yaml` in `create_document_loader`, honor each manifest `contentType`, preserve Link/redirect metadata, and add YAML alternates. Remove the in-scope YAML-LD `idRegex` skips rather than masking failures.
+- [ ] Run the YAML-LD manifest suite through the façade's `expand`, `compact`, `flatten`, `frame`, `to_rdf`, and `normalize` paths on the full matrix and with both Requests and AioHTTP. Adapter tests own parser/media fixtures; PyLD owns JSON-LD operation and manifest conformance. Any remaining non-normative Extended-profile test is skipped only by its manifest `normative: false` marker, with no broad regular-expression skip.
+
+### Ship jointly
+
+- [ ] Build PyLD wheels and install-test `PyLD[yaml-ld]` and `PyLD[cli,yaml-ld]` at both ends of the adapter version range. Gate release on the complete adapter matrix, PyLD matrix, adapter fixtures, PyLD manifests, CLI byte-output tests, strict documentation build, and package-isolation test.
+- [ ] Release adapter `1.0.0`, then the PyLD feature release. PyLD owns façade, HTTP, cache, and CLI regressions; adapter maintainers own parser CVEs. For an adapter defect, publish a compatible adapter patch or constrain PyLD's extra bound and release coordinated advisories.
+
+??? info "Decisions"
+    This conditional roadmap supports [Implement YAML-LD support in …](index.md). It is not an adopted implementation plan until that ADR selects this alternative.
diff --git a/docs/project/decisions/examples/intro.yamlld b/docs/project/decisions/examples/intro.yamlld
new file mode 100644
index 00000000..e7f685d0
--- /dev/null
+++ b/docs/project/decisions/examples/intro.yamlld
@@ -0,0 +1,19 @@
+"@context":
+  - https://json-ld.org/contexts/dollar-convenience.jsonld
+  - schema: https://schema.org/
+    dbo: http://dbpedia.org/ontology/
+    dbp: http://dbpedia.org/property/
+    dbr: http://dbpedia.org/resource/
+    xsd: http://www.w3.org/2001/XMLSchema#
+    dbp:discovered:
+      "@type": xsd:date
+    dbp:star:
+      "@type": "@id"
+
+$id: dbr:Proxima_Centauri_b
+$type: dbo:Planet
+schema:description: >-
+  The closest known exoplanet to Earth,
+  orbiting in Proxima Centauri's habitable zone.
+dbp:discovered: 2016-08-24
+dbp:star: dbr:Proxima_Centauri
diff --git a/docs/project/decisions/use-pyld-jsonld-expand-for-yaml-ld.md b/docs/project/decisions/use-pyld-jsonld-expand-for-yaml-ld.md
new file mode 100644
index 00000000..d3e03cfe
--- /dev/null
+++ b/docs/project/decisions/use-pyld-jsonld-expand-for-yaml-ld.md
@@ -0,0 +1,49 @@
+---
+title: Use `pyld.jsonld.expand()` for YAML-LD expansion
+status: decided
+date: 2026-09-01
+author: Anatoly Scherbakov
+tags: [decision]
+hide: [toc]
+---
+
+# Use `pyld.jsonld.expand()` for YAML-LD expansion
+
+{{ adr_metadata(date, status) }}
+
+*[DRY]: Don't Repeat Yourself
+
+## :material-text-box-outline: Context
+
+We are considering YAML-LD support in PyLD based on the
+[YAML-LD specification](https://www.w3.org/TR/yaml-ld-10/), which reuses the
+JSON-LD data model and processing API. Here is an example:
+
+{{ source_file('project/decisions/examples/intro.yamlld') }}
+
+The JSON-LD API defines
+[`JsonLdProcessor.expand(input, options)`](https://www.w3.org/TR/json-ld11-api/#idl-def-jsonldprocessor-expand-input-options)
+as an example expansion endpoint.
+
+How should we expand a YAML-LD document programmatically?
+
+## :material-arrow-decision-outline: Decision
+
+<table data-adr-comparison markdown="1">
+  <tr markdown="span">
+    <th>Expansion function</th>
+    <th>Decision</th>
+  </tr>
+  <tr markdown="span">
+    <th class="chosen">[:material-arrow-expand: `pyld.jsonld.expand()`](/pyld/reference/expand/)</th>
+    <td class="chosen">:white_check_mark: Chosen</td>
+  </tr>
+  <tr markdown="span">
+    <th class="excl">`pyld.yaml_ld.expand()`</th>
+    <td class="excl">:x: Creates a competing expand API, violating [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)</td>
+  </tr>
+  <tr markdown="span">
+    <th class="excl">`yaml_ld.expand()`</th>
+    <td class="excl">:x: Creates a competing expand API, violating [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)</td>
+  </tr>
+</table>
diff --git a/docs/project/index.md b/docs/project/index.md
index 1c579c95..03198223 100644
--- a/docs/project/index.md
+++ b/docs/project/index.md
@@ -13,6 +13,12 @@ Architecture Decision Records (ADRs) document the technical choices taken during
 
 <div id="adr-index" markdown>
 
+!!! warning inline "[Implement YAML-LD support in …](decisions/choose-where-to-host-yaml-ld-support/index.md)"
+    :material-calendar-clock: 19 July 2026
+
+    Implement it directly in PyLD, or have PyLD use a separate parser-only
+    YAML-LD adapter.
+
 !!! success inline "[Use `requests-cache` for persistent HTTP caching in synchronous Python code](decisions/use-requests-cache-for-sync-http-caching-in-document-loaders/)"
     :material-calendar-clock: 29 June 2026
 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index f2129d5d..1bb3a529 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -94,3 +94,18 @@
 .md-typeset :is(th, td).adr-col-rejected {
   background-color: var(--adr-col-rejected-bg);
 }
+
+/* ADR comparison row tints. */
+:root,
+[data-md-color-scheme="slate"] {
+  --adr-chosen-bg: color-mix(in srgb, #00c853 10%, transparent);
+  --adr-excluded-bg: color-mix(in srgb, #ff1744 10%, transparent);
+}
+
+.md-typeset :is(th, td).chosen {
+  background-color: var(--adr-chosen-bg);
+}
+
+.md-typeset :is(th, td).excl {
+  background-color: var(--adr-excluded-bg);
+}
diff --git a/docs_macros.py b/docs_macros.py
index fade8e17..cd5a7488 100644
--- a/docs_macros.py
+++ b/docs_macros.py
@@ -11,14 +11,25 @@
 from yaml import SafeLoader
 
 ROOT_DIR = Path(__file__).resolve().parent
-EXAMPLES_DIR = ROOT_DIR / 'docs' / 'examples'
+DOCS_DIR = ROOT_DIR / 'docs'
+EXAMPLES_DIR = DOCS_DIR / 'examples'
 sys.path.insert(0, str(ROOT_DIR / 'lib'))
 sys.path.insert(0, str(ROOT_DIR / 'tests'))
 
+_SOURCE_LANG = {
+    '.yamlld': 'yaml',
+    '.yaml': 'yaml',
+    '.yml': 'yaml',
+    '.jsonld': 'json',
+    '.json': 'json',
+    '.py': 'python',
+}
+
 MANIFEST_BASES = {
     'frame-manifest': 'https://w3c.github.io/json-ld-framing/tests',
     'manifest-urgna2012': 'https://w3c.github.io/rdf-canon/tests',
     'manifest-urdna2015': 'https://w3c.github.io/rdf-canon/tests',
+    'manifest': 'https://w3c.github.io/yaml-ld/tests',
 }
 DEFAULT_TEST_BASE = 'https://w3c.github.io/json-ld-api/tests'
 
@@ -26,6 +37,7 @@
 _MANIFEST_PATHS = (
     ROOT_DIR / 'specifications' / 'json-ld-api' / 'tests',
     ROOT_DIR / 'specifications' / 'json-ld-framing' / 'tests',
+    ROOT_DIR / 'specifications' / 'yaml-ld' / 'tests',
 )
 
 
@@ -33,12 +45,19 @@ def _parse_skip_id_regex(pattern):
     match = _SKIP_ID_PATTERN.fullmatch(pattern)
     if not match:
         return None
-    return match.group('manifest'), match.group('test_id')
+    # Suite-scoped patterns may include a path prefix, e.g.
+    # .*yaml-ld/tests/manifest#two-documents-from-stream$
+    manifest = match.group('manifest')
+    if '/' in manifest:
+        manifest = manifest.rsplit('/', 1)[-1]
+    return manifest, match.group('test_id')
 
 
 def _test_url(manifest, test_id):
-    base = MANIFEST_BASES.get(manifest, DEFAULT_TEST_BASE)
-    return f'{base}/{manifest}.html#{test_id}'
+    # Basename only — suite-scoped regex captures may still contain '/'.
+    manifest_name = manifest.rsplit('/', 1)[-1]
+    base = MANIFEST_BASES.get(manifest_name, DEFAULT_TEST_BASE)
+    return f'{base}/{manifest_name}.html#{test_id}'
 
 
 def _jsonld_values(data, key):
@@ -59,7 +78,11 @@ def _manifest_entries():
     for manifest_dir in _MANIFEST_PATHS:
         if not manifest_dir.exists():
             continue
-        for path in sorted(manifest_dir.glob('*-manifest.jsonld')):
+        paths = {
+            *manifest_dir.glob('*-manifest.jsonld'),
+            *manifest_dir.glob('manifest.jsonld'),
+        }
+        for path in sorted(paths):
             data = json.loads(path.read_text())
             manifest = path.stem
             for entry in _jsonld_values(data, 'sequence'):
@@ -82,6 +105,11 @@ def _skip_reason(test_type, skip, test):
     for pattern in skip.get('idRegex', []):
         if re.match(pattern, test_id):
             return f'Explicit skip (`{test_type}`)'
+        # Suite-scoped patterns (e.g. .*yaml-ld/tests/manifest#id$) still
+        # refer to the same short manifest#id used in local entries.
+        parsed = _parse_skip_id_regex(pattern)
+        if parsed and f'{parsed[0]}#{parsed[1]}' == test_id:
+            return f'Explicit skip (`{test_type}`)'
 
     for pattern in skip.get('descriptionRegex', []):
         if re.match(pattern, entry.get('description', '')):
@@ -114,6 +142,13 @@ def _example_path(name):
     return path
 
 
+def _docs_path(rel):
+    path = (DOCS_DIR / rel).resolve()
+    if not path.is_relative_to(DOCS_DIR.resolve()):
+        raise ValueError(f'Invalid docs path: {rel}')
+    return path
+
+
 def _github_branch():
     branch = os.environ.get('GITHUB_REF_NAME')
     if branch:
@@ -129,10 +164,20 @@ def _github_branch():
     return 'master'
 
 
-def _example_github_url(name, repo_url):
-    rel_path = Path('docs/examples') / name
+def _docs_github_url(rel, repo_url):
     branch = 'master'
-    return f'{repo_url.rstrip("/")}/blob/{branch}/{rel_path.as_posix()}'
+    return f'{repo_url.rstrip("/")}/blob/{branch}/docs/{Path(rel).as_posix()}'
+
+
+def _example_github_url(name, repo_url):
+    return _docs_github_url(Path('examples') / name, repo_url)
+
+
+def _example_admonition(title, body, indent=0):
+    content_indent = indent + 4
+    pad = ' ' * content_indent
+    indented = '\n'.join(f'{pad}{line}' for line in body.splitlines())
+    return f'!!! example "{title}"\n\n{indented}\n'
 
 
 def _human_date(value):
@@ -169,7 +214,17 @@ def _adr_metadata_date(value):
     return f':material-calendar-clock: {_human_date(value)}'
 
 
-def _adr_metadata(date, status):
+def _adr_metadata_prerequisite(value):
+    if not value:
+        return ''
+    title = value.get('title')
+    url = value.get('url')
+    if not title or not url:
+        return ''
+    return f'Depends on [{title}]({url})'
+
+
+def _adr_metadata(date, status, prerequisite=None):
     kind = _ADR_STATUS_ADMONITION.get(str(status).lower(), 'note')
     parts = []
     label = _adr_status_label(status)
@@ -178,6 +233,9 @@ def _adr_metadata(date, status):
     date_part = _adr_metadata_date(date)
     if date_part:
         parts.append(date_part)
+    prerequisite_part = _adr_metadata_prerequisite(prerequisite)
+    if prerequisite_part:
+        parts.append(prerequisite_part)
     title = ' · '.join(parts)
     return f'!!! {kind} "{title}"\n'
 
@@ -221,8 +279,8 @@ def adr_status(value):
         return _adr_status(value)
 
     @env.macro
-    def adr_metadata(date, status):
-        return _adr_metadata(date, status)
+    def adr_metadata(date, status, prerequisite=None):
+        return _adr_metadata(date, status, prerequisite)
 
     @env.macro
     def bundled_contexts_table():
@@ -335,10 +393,7 @@ def example(name, output_syntax=None, indent=0):
             f'```python\n{source}```\n\n'
             f'```{output_lang} title="Output"\n{result.stdout}```'
         )
-        content_indent = indent + 4
-        pad = ' ' * content_indent
-        indented = '\n'.join(f'{pad}{line}' for line in body.splitlines())
-        return f'!!! example "{title}"\n\n{indented}\n'
+        return _example_admonition(title, body, indent=indent)
 
     @env.macro
     def example_data(name, indent=0):
@@ -355,10 +410,7 @@ def example_data(name, indent=0):
             f'</span>'
         )
         body = f'```{lang}\n{source}\n```'
-        content_indent = indent + 4
-        pad = ' ' * content_indent
-        indented = '\n'.join(f'{pad}{line}' for line in body.splitlines())
-        return f'!!! example "{title}"\n\n{indented}\n'
+        return _example_admonition(title, body, indent=indent)
 
     @env.macro
     def terminal(command, title='pyld', indent=0):
@@ -393,3 +445,18 @@ def terminal(command, title='pyld', indent=0):
         return lines[0] + '\n' + '\n'.join(
             f'{pad}{line}' if line else line for line in lines[1:]
         )
+
+    @env.macro
+    def source_file(rel, indent=0):
+        """Include a docs file in an example admonition with a GitHub source link."""
+        path = _docs_path(rel)
+        source = path.read_text()
+        github_url = _docs_github_url(rel, env.conf['repo_url'])
+        lang = _SOURCE_LANG.get(path.suffix.lower(), 'text')
+        title = (
+            f'Example<span class="example-source-link" markdown>'
+            f':fontawesome-brands-github: [`{path.name}`]({github_url})'
+            f'</span>'
+        )
+        body = f'```{lang}\n{source}```'
+        return _example_admonition(title, body, indent=indent)
diff --git a/mkdocs.yml b/mkdocs.yml
index 589c2c78..b57666a4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -30,6 +30,7 @@ theme:
 
 markdown_extensions:
   - admonition
+  - abbr
   - attr_list
   - md_in_html
   - pymdownx.details
@@ -38,6 +39,10 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight:
       anchor_linenums: true
+  - pymdownx.snippets:
+      base_path:
+        - docs
+      check_paths: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
diff --git a/specifications/yaml-ld b/specifications/yaml-ld
new file mode 160000
index 00000000..af4c9c8e
--- /dev/null
+++ b/specifications/yaml-ld
@@ -0,0 +1 @@
+Subproject commit af4c9c8eb77454645a0b16e69ec16b28a322ff06
diff --git a/tests/runtests.py b/tests/runtests.py
index 10b1ea18..1f195c43 100644
--- a/tests/runtests.py
+++ b/tests/runtests.py
@@ -91,14 +91,16 @@
     'https://w3c.github.io/json-ld-api/tests',
     'https://w3c.github.io/json-ld-framing/tests',
     'https://github.com/json-ld/normalization/tests',
-    'https://w3c.github.io/rdf-canon/tests/vocab#'
+    'https://w3c.github.io/rdf-canon/tests/vocab#',
+    'https://w3c.github.io/yaml-ld/tests',
 ]
 
 SPEC_DIRS = [
     '../specifications/json-ld-api/tests/',
     '../specifications/json-ld-framing/tests/',
     '../specifications/normalization/tests/',
-    '../specifications/rdf-canon/tests/'
+    '../specifications/rdf-canon/tests/',
+    '../specifications/yaml-ld/tests/',
 ]
 
 # NOTE: The following TestRunner class can be removed because pytest now
@@ -751,6 +753,8 @@ def load_locally(url):
         url_no_frag = strip_fragment(url)
         if not content_type and url_no_frag.endswith('.jsonld'):
             content_type = 'application/ld+json'
+        if not content_type and url_no_frag.endswith('.yamlld'):
+            content_type = 'application/ld+yaml'
         if not content_type and url_no_frag.endswith('.json'):
             content_type = 'application/json'
         if not content_type and url_no_frag.endswith('.html'):
@@ -953,6 +957,11 @@ def write(self, filename):
             # skip tests where behavior changed for a 1.1 processor
             # see JSON-LD 1.0 Errata
             'specVersion': ['json-ld-1.0'],
+            # YAML-LD suite: only currently failing cases (passing cases stay active)
+            'idRegex': [
+                '.*yaml-ld/tests/manifest#compact-local-json-ld-context$',
+                '.*yaml-ld/tests/manifest#compact-local-yaml-ld-context$',
+            ],
         },
         'fn': 'compact',
         'params': [
@@ -984,6 +993,50 @@ def write(self, filename):
             # skip tests where behavior changed for a 1.1 processor
             # see JSON-LD 1.0 Errata
             'specVersion': ['json-ld-1.0'],
+            # YAML-LD suite: only currently failing cases (passing cases stay active)
+            'idRegex': [
+                '.*yaml-ld/tests/manifest#cir-mapping-key-1-negative$',
+                '.*yaml-ld/tests/manifest#cir-mapping-key-2-negative$',
+                '.*yaml-ld/tests/manifest#cir-mapping-key-3-negative$',
+                '.*yaml-ld/tests/manifest#cir-mapping-key-4-negative$',
+                '.*yaml-ld/tests/manifest#cir-mapping-key-5-negative$',
+                '.*yaml-ld/tests/manifest#cir-scalar-core-1-positive$',
+                '.*yaml-ld/tests/manifest#cir-scalar-i18n-1-positive$',
+                '.*yaml-ld/tests/manifest#cir-scalar-other-1-positive$',
+                '.*yaml-ld/tests/manifest#cr-comments-1-positive$',
+                '.*yaml-ld/tests/manifest#cr-utf8-1-positive$',
+                '.*yaml-ld/tests/manifest#cr-utf8-2-negative$',
+                '.*yaml-ld/tests/manifest#cr-well-formed-1-positive$',
+                '.*yaml-ld/tests/manifest#aa-cycles-1-positive$',
+                '.*yaml-ld/tests/manifest#aa-cycles-3-positive$',
+                '.*yaml-ld/tests/manifest#html-and-yaml-streams$',
+                '.*yaml-ld/tests/manifest#mixed-script-types$',
+                '.*yaml-ld/tests/manifest#html-dedent-needed$',
+                '.*yaml-ld/tests/manifest#html-dedent-not-needed$',
+                '.*yaml-ld/tests/manifest#two-documents-from-stream$',
+                '.*yaml-ld/tests/manifest#one-document-from-stream$',
+                '.*yaml-ld/tests/manifest#local-json-ld-context$',
+                '.*yaml-ld/tests/manifest#local-yaml-ld-context$',
+                '.*yaml-ld/tests/manifest#core-bool-true$',
+                '.*yaml-ld/tests/manifest#core-bool-false$',
+                '.*yaml-ld/tests/manifest#core-bool-true-title$',
+                '.*yaml-ld/tests/manifest#core-bool-false-upper$',
+                '.*yaml-ld/tests/manifest#core-null-null$',
+                '.*yaml-ld/tests/manifest#core-null-tilde$',
+                '.*yaml-ld/tests/manifest#core-null-upper$',
+                '.*yaml-ld/tests/manifest#core-int-decimal$',
+                '.*yaml-ld/tests/manifest#core-int-octal$',
+                '.*yaml-ld/tests/manifest#core-int-hex$',
+                '.*yaml-ld/tests/manifest#core-float-basic$',
+                '.*yaml-ld/tests/manifest#core-float-scientific$',
+                '.*yaml-ld/tests/manifest#core-date-ymd$',
+                '.*yaml-ld/tests/manifest#core-yaml11-yes$',
+                '.*yaml-ld/tests/manifest#core-yaml11-no$',
+                '.*yaml-ld/tests/manifest#core-yaml11-on$',
+                '.*yaml-ld/tests/manifest#core-yaml11-off$',
+                '.*yaml-ld/tests/manifest#core-yaml11-yes-title$',
+                '.*yaml-ld/tests/manifest#core-yaml11-yes-upper$',
+            ],
         },
         'fn': 'expand',
         'params': [read_test_url('input'), create_test_options()],
@@ -994,6 +1047,10 @@ def write(self, filename):
             # skip tests where behavior changed for a 1.1 processor
             # see JSON-LD 1.0 Errata
             'specVersion': ['json-ld-1.0'],
+            # YAML-LD suite: only currently failing cases (passing cases stay active)
+            'idRegex': [
+                '.*yaml-ld/tests/manifest#flatten$',
+            ],
         },
         'fn': 'flatten',
         'params': [
@@ -1008,6 +1065,10 @@ def write(self, filename):
             # skip tests where behavior changed for a 1.1 processor
             # see JSON-LD 1.0 Errata
             'specVersion': ['json-ld-1.0'],
+            # YAML-LD suite: only currently failing cases (passing cases stay active)
+            'idRegex': [
+                '.*yaml-ld/tests/manifest#frame-t0001$',
+            ],
         },
         'fn': 'frame',
         'params': [
@@ -1040,6 +1101,12 @@ def write(self, filename):
             # skip tests where behavior changed for a 1.1 processor
             # see JSON-LD 1.0 Errata
             'specVersion': ['json-ld-1.0'],
+            # YAML-LD suite: only currently failing cases (passing cases stay active)
+            'idRegex': [
+                '.*yaml-ld/tests/manifest#aa-information-1-positive$',
+                '.*yaml-ld/tests/manifest#cir-scalar-core-2-positive$',
+                '.*yaml-ld/tests/manifest#cir-scalar-other-2-positive$',
+            ],
         },
         'fn': 'to_rdf',
         'params': [