Skip to content

Update documentation for cdx-core v0.7.0 alignment #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gvonnessi merged 1 commit into from
Feb 17, 2026
Merged

Update documentation for cdx-core v0.7.0 alignment #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

## [0.6.0] - 2026-02-17

### Changed
- **Mark namespacing**: semantic marks now use `semantic:` prefix (`semantic:citation`, `semantic:entity`, `semantic:glossary`), academic marks use `academic:` prefix (`academic:theorem-ref`, `academic:equation-ref`, `academic:algorithm-ref`). Core marks (`footnote`, `anchor`, `math`, `link`, `code`) are unchanged.
- **Measurement** is now a core block type (`measurement`) with a `display` field containing the original text. Removed `semantic:measurement` type and `schema` (schema.org QuantitativeValue) field.
- **Figure subfigures** moved from `children` to a dedicated `subfigures` array. Subfigure objects have `id`, `label`, and `children` fields (no `type`).
- **Inline math** mark now includes `source` field containing the LaTeX string alongside `format: "latex"`.
- **Content version** bumped from `0.1` to `0.7.0` to align with cdx-core serialization format.
- Extension tracking now covers inline marks (semantic and academic), not just blocks.
- Reader accepts both namespaced and legacy non-namespaced mark formats for backward compatibility.

## [0.5.0] - 2026-02-04

### Added
Expand Down
29 changes: 15 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ pandoc -f cdx-reader.lua output.json -o document.tex
pandoc -f cdx-reader.lua output.json -o document.html
```

The reader handles core block types (paragraphs, headings, lists, code blocks, blockquotes, tables, math, images, figures, definition lists, admonitions) and academic extension blocks (theorems, proofs, exercises, algorithms, abstracts, equation groups). Semantic blocks like `semantic:term`, `semantic:measurement`, and `semantic:ref` are converted to their closest Pandoc equivalents. Footnotes are restored via inline references. Extension blocks without equivalents (e.g., `semantic:bibliography`, `semantic:glossary`) are skipped.
The reader handles core block types (paragraphs, headings, lists, code blocks, blockquotes, tables, math, images, figures, definition lists, admonitions, measurements) and academic extension blocks (theorems, proofs, exercises, algorithms, abstracts, equation groups). Semantic blocks like `semantic:term` and `semantic:ref` are converted to their closest Pandoc equivalents. The reader accepts both namespaced (e.g., `semantic:citation`) and legacy non-namespaced mark formats. Footnotes are restored via inline references. Extension blocks without equivalents (e.g., `semantic:bibliography`, `semantic:glossary`) are skipped.

## Features

Expand All @@ -77,8 +77,9 @@ The reader handles core block types (paragraphs, headings, lists, code blocks, b
| Math (display) | math | LaTeX format, display=true |
| Math (inline) | math mark | LaTeX format on text node |
| DefinitionList | definitionList | Core block with term/description items |
| Span (.measurement) | measurement | Core block: value, unit, display |
| DefinitionList (.glossary) | semantic:term | Glossary Div context only |
| Cite | citation mark | refs, locator, prefix, suffix, suppressAuthor |
| Cite | semantic:citation mark | refs, locator, prefix, suffix, suppressAuthor |
| Note | semantic:footnote | Superscript ref + block content |
| Image | image | src, alt, title, width, height |
| Figure | figure | Container with image children + figcaption |
Expand All @@ -101,10 +102,10 @@ The reader handles core block types (paragraphs, headings, lists, code blocks, b
| Emph | italic |
| Code | code |
| Link | link (with href, title) |
| Link (#thm-*, #lem-*, ...) | theorem-ref |
| Link (#eq-*) | equation-ref |
| Link (#alg-*) | algorithm-ref |
| Math (inline) | math (format: latex) |
| Link (#thm-*, #lem-*, ...) | academic:theorem-ref |
| Link (#eq-*) | academic:equation-ref |
| Link (#alg-*) | academic:algorithm-ref |
| Math (inline) | math (format: latex, source) |
| Strikeout | strikethrough |
| Underline | underline |
| Superscript | superscript |
Expand All @@ -124,7 +125,7 @@ Link text to knowledge bases (Wikidata, DBpedia, etc.):
[Large Hadron Collider]{.entity uri="https://www.wikidata.org/wiki/Q83492" entityType="Place" source="Wikidata"}
```

Produces an `entity` mark with `uri`, `entityType`, and optional `source` fields.
Produces a `semantic:entity` mark with `uri`, `entityType`, and optional `source` fields.

#### Glossary References

Expand All @@ -137,7 +138,7 @@ We discuss [CRDT]{.glossary ref="term-crdt"} technologies.
[eventual consistency]{.glossary}
```

Produces a `glossary` mark with `ref` field pointing to a `semantic:term` block ID.
Produces a `semantic:glossary` mark with `ref` field pointing to a `semantic:term` block ID.

#### Measurements

Expand All @@ -149,7 +150,7 @@ The sample weighed [42.5 kg]{.measurement value="42.5" unit="kg"}.
Temperature reached [100 °C]{.measurement value="100" unit="°C"}.
```

Produces a `semantic:measurement` block with `value`, `unit`, and schema.org `QuantitativeValue` metadata.
Produces a core `measurement` block with `value`, `unit`, and `display` (the original text).

### Academic Extension Blocks

Expand Down Expand Up @@ -199,7 +200,7 @@ Admonition classes: `note`, `warning`, `tip`, `danger`, `important`, `caution`.

Aligned LaTeX environments (`\begin{align}`, `\begin{gather}`, `\begin{split}`) in display math are automatically detected and converted to `academic:equation-group` blocks.

Cross-references to academic blocks use standard Markdown links with `#`-prefixed IDs (e.g., `[Theorem 1](#thm-max)`). Links targeting `#thm-*`, `#lem-*`, `#eq-*`, `#alg-*`, etc. are converted to typed reference marks (`theorem-ref`, `equation-ref`, `algorithm-ref`).
Cross-references to academic blocks use standard Markdown links with `#`-prefixed IDs (e.g., `[Theorem 1](#thm-max)`). Links targeting `#thm-*`, `#lem-*`, `#eq-*`, `#alg-*`, etc. are converted to namespaced reference marks (`academic:theorem-ref`, `academic:equation-ref`, `academic:algorithm-ref`).

### Metadata Mapping

Expand Down Expand Up @@ -237,7 +238,7 @@ The writer produces a JSON structure with three sections:
}
},
"content": {
"version": "0.1",
"version": "0.7.0",
"blocks": [...]
},
"dublin_core": {
Expand Down Expand Up @@ -363,16 +364,16 @@ Display math should use double dollar signs or the equation environment:
$$E = mc^2$$
```

Inline math uses single dollar signs: `$x = y$`. Inline math is preserved as a `math` mark on text nodes (stays inside the paragraph). Display math produces a block-level `math` block. Aligned LaTeX environments (`align`, `gather`, `split`) are automatically detected and converted to `academic:equation-group` blocks.
Inline math uses single dollar signs: `$x = y$`. Inline math is preserved as a `math` mark on text nodes (stays inside the paragraph) with `format: "latex"` and `source` containing the LaTeX string. Display math produces a block-level `math` block. Aligned LaTeX environments (`align`, `gather`, `split`) are automatically detected and converted to `academic:equation-group` blocks.

### Reader round-trip loses semantic data

The reader converts Codex back to standard Pandoc elements. Most block types survive round-trip faithfully:

- **Core blocks**: paragraphs, headings, lists, tables, code, math, images, figures, definition lists, admonitions all round-trip cleanly.
- **Academic blocks**: theorems (variant, id, title), proofs (of, method), exercises (difficulty, hints, solutions), algorithms (title, pseudocode), abstracts (keywords), and equation groups (reconstructed LaTeX environments) all survive via Pandoc Div attributes.
- **Semantic blocks**: `semantic:term` round-trips via DefinitionList, `semantic:measurement` via Span attributes. `semantic:bibliography` and `semantic:glossary` are skipped as they have no direct Pandoc equivalent.
- **Inline marks**: formatting, links, math, citations, footnotes, entity URIs, and academic cross-references all survive round-trip.
- **Semantic blocks**: `semantic:term` round-trips via DefinitionList, `measurement` via Span attributes. `semantic:bibliography` and `semantic:glossary` are skipped as they have no direct Pandoc equivalent.
- **Inline marks**: formatting, links, math, `semantic:citation`, footnotes, `semantic:entity` URIs, `semantic:glossary` references, and `academic:*-ref` cross-references all survive round-trip.

## Related Projects

Expand Down