Publication quality
Common publication issues and how the pipeline catches them. From a TC editor's point of view: what does a failed publication look like, what did the source MD do, how do you fix it.
1.The layers of checks¶
The pipeline applies three layers of automated checks, and the same defect classes are enforceable in the TC's own build before submission.
| Layer | When | What it catches |
|---|---|---|
| Pre-render lint | In step 2.0, on the HTML that step 1.0 produced, before the PDF is printed | Structural issues in the rendered HTML that indicate a problem with the source MD or the renderer's interaction with it |
| Post-render assertions | After PDF generation | Issues that only show up in the printed PDF: a title printed twice on the cover page, a build-runner path in the text |
| Acceptance checks (pub-check) | In the TC's own build, before the vote, and again by TC Administration at intake and before go-live | Every defect class below, plus stage naming, front matter, links and packaging |
A TC's own clean run predicts intake acceptance; it never substitutes for it, because TC Administration runs the same checks again. If a check fails (for pub-check, a blocker; its warnings are reported but do not stop a publication) the publication stops, the offending issue is reported by name, and the source is not deployed.
2.Pre-render issues¶
2.1Title rendered more than once on the cover page¶
What it looks like. The PDF cover page shows the specification title twice in a row, e.g.:
Data Provenance Metadata Version 1.0
Data Provenance Metadata Version 1.0
Committee Specification Draft 01
07 May 2026What caused it. The source MD has more than one top-level heading matching the document title, or pandoc has emitted a separate title block on top of the body H1.
How to fix it. Ensure exactly one # Title heading at the top of the source, and let the citation block use lower-level headings.
2.2Pandoc title-block leakage¶
What it looks like. The published HTML contains a stray <header id="title-block-header">...</header> element that duplicates the title.
What caused it. Pandoc emits this block when invoked with --metadata title=. The pipeline strips it during rendering, but a malformed source MD can interact with the strip step.
How to fix it. Usually no source change required; the pipeline strips this automatically. If the lint flags it, the source has an unusual title shape that the pipeline operator can investigate.
2.3Build-runner path leaked into HTML¶
What it looks like. The published HTML contains a reference to /home/runner/... somewhere in a <link> or <img> tag.
What caused it. Pandoc has serialised an absolute filesystem path from the build environment into the output.
How to fix it. No source change required. The pipeline catches this and refuses to deploy.
2.4Image path with a double slash¶
What it looks like. The image fails to load on the published page, or in the PDF.
What caused it. The source MD references an image with a path like ./images//figure.svg (double slash). Browsers tolerate the double; the CDN does not.
How to fix it. Remove the double slash in the source: ./images/figure.svg.
2.5Horizontal rule between the OASIS logo and the title¶
What it looks like. The PDF cover renders with a blank page between the OASIS logo and the spec title.
What caused it. A Markdown horizontal rule (--- on its own line) immediately follows the logo. The publication CSS treats this as a PDF page break.
How to fix it. Remove the --- between the logo and the title H1 in the source MD.
2.6YAML code-block info string with trailing text¶
What it looks like. A YAML code block in the published HTML renders as a single line of inline code rather than a multi-line syntax-highlighted block. Each affected block is collapsed.
What caused it. The source MD has a fenced code block opening like:
```yaml <!-- json-path($.foo.bar) -->
key: value
...
```Pandoc's classic fenced-code parser does not accept trailing text after the language token. The pipeline rewrites this pattern before pandoc sees it, so this is usually caught and handled automatically.
How to fix it. No action is needed for this publication; the pipeline rewrites the fence. The lint reports it so the editor can remove the trailing text in the next working draft.
2.7Image source defect¶
What it looks like. The publication fails with a message naming an <img> tag in the source.
What caused it. One of:
- Empty
srcattribute - Image file referenced but not present in the publication directory
- Path traversal outside the publication directory
- Absolute filesystem path
- Unsafe URL scheme (
javascript:,file:,ftp:) - Filename extension does not match the actual file contents
- SVG containing
<script>, event handlers, or external image references - Image significantly larger than the per-image cap
How to fix it. Each case has a specific cause in the source. The lint message names the offending image and the specific defect. Fix the reference in the source MD or replace the image file.
3.Post-render assertions¶
These run after the PDF is generated, against the rendered output.
3.1Cover page title appears more than once¶
What it looks like. Same symptom as 2.1, caught at the PDF stage if the pre-render lint missed it (e.g. the strip step was bypassed).
How to fix it. Same as 2.1.
3.2Build-runner path leaked into the PDF¶
What it looks like. The rendered PDF text contains /home/runner/... somewhere in the body.
What caused it. Same as 2.3, but the leak survived the HTML strip and reached the PDF.
How to fix it. No source change required. The pipeline catches this and refuses to deploy.
4.Failed publications¶
The publication operator surfaces the specific failure by name and, where the cause is in the source MD, points to the offending location. The TC editor fixes the source on the editorial branch, the operator re-runs the chain, the checks pass, and the publication goes live.
The TC editor never has to read the pipeline source code or guess what's wrong. The lint and assertions are designed to name the problem in terms the editor can act on.
5.Defect identifiers for cross-reference¶
When the publication operator or a reviewer cites a defect by ID, the mapping is:
| ID | Layer | Name (in this page) |
|---|---|---|
| D1 | Pre-render | Title rendered more than once on the cover page |
| D2 | Pre-render | Pandoc title-block leakage |
| D3 | Pre-render | Build-runner path leaked into HTML |
| D4 | Pre-render | Image path with a double slash |
| D5 | Pre-render | Horizontal rule between the OASIS logo and the title |
| D6 | Pre-render | YAML code-block info string with trailing text |
| D7 | Pre-render | Image source defect |
| A1 | Post-render | Cover page title appears more than once |
| A2 | Post-render | Build-runner path leaked into the PDF |
New defect classes are added when a new regression is caught in the field. The ID sequence is append-only; old IDs are never reused.
The full registry is also enforced at intake by pub-check (D1-D3 as html-residue, D4 as double-slash, D5 as cover-hr, D6 as fence-collapse, D7 as image-policy, A1/A2 as pdf-cover), so a TC can catch every one of these before submission: python3 oasis_pub_check.py <stage-dir>.
6.Changes to the PDF in recent releases¶
The PDF step changed three times between 27 and 30 September 2026. A TC that compares a new PDF with its previous draft will see these differences; none needs a change to the source. The Publication Console's steps run the toolkit's main branch, so they pick up each change as soon as it is merged. A TC repository that pins the toolkit (see architecture) gets them when it moves its pin to that release or later.
| Release | What changed in the PDF | Where it showed |
|---|---|---|
| v0.4.0 | A4 paper, the published OASIS footer (document name, track, copyright line, date), no running header, and a table of contents numbered from the printed pages. Earlier PDFs were US Letter with "Standards Track Work Product" as a running header on every document, Committee Notes included | Every PDF the Publication Console has built since 27 September 2026 |
| v0.4.1 | A contents entry that wraps onto a second line ends that line with its page number. Before, the number sat on the first line and the dot leader ran along the second line to nothing | DMLex, contents entry F.1.1 |
| v0.5.0 | A multi-line code block prints as one block. Before, each line printed in its own overlapping, clipped box; the published HTML was not affected | CSAF v2.1 CSD03: 447 of 667 code blocks, in both renderers |
7.Related documentation¶
- Publication overview: the shape of a publication
- Publication configuration: the rendering settings and who can change them
- Getting started: onboarding a new TC
- TC Handbook: the process rules; this page covers the mechanics that enforce them
- Specification guidelines: the naming directives (v1.7 current) and naming guidelines that bind stage tokens, filenames, and URIs
- pub-check: the OASIS publication checks, including this page's full defect registry, runnable in your own CI before the vote. The check set grows as new failure modes are found; CHECKS.md is the live inventory, and
--list-checksasserts it from the code