ox-w3ctr — org export backend for W3C TR CSS style

Based on Org-mode’s ox-html.el and CSS of W3C Technical Report tr-design’s base.css.

Status

Emacs Version	30.1	31.1	32.1
Package Version	0.2	0.3	0.4
Date	[2025-02-23]	[2026-08-24]	2027?

The current ox-w3ctr has not yet completed a full refactoring of the ox-html code, though it’s already largely usable. I plan to release version 0.4 when Emacs 32.1 comes out.

When version 0.4 is released, the package should no longer introduce breaking changes, and Emacs 32.1 will be the minimum supported version. In a sense, 0.4 will be the first official release.

Install and Use

Please use Emacs 32.0.50 or above. Download this repo and add it to load-path, or use package-vc like this:

M-x package-vs-install https://github.com/include-yy/ox-w3ctr RET

After installation and load, use C-c C-e w o to export a org buffer to HTML file. See more information from docstrings and comments (at least now).

TODO list [0/4]

1. [ ] Totally Refactor from ox-html.
2. [ ] Fully detailed documentation.
3. [ ] A friendly introductive video.
4. [ ] CI/CD support.

Roadmap

• Options tidy-up. The :options-alist is a grab-bag: a few entries are grouped, most are not. Order every entry, consider replacing cumbersome string options with *-function ones. Chart compatibility with ox-html for each option. Known divergences to chart: :html-link-use-abs-url is unimplemented (FIXME in org-w3ctr--link-path); the legacy home/up bar emits our own <nav id“navbar”>= markup, deliberately not ox-html’s <div id“org-div-home-and-up”>=. :html-home/up-format keeps its ox-html keyword compatibility (HTML_HOME/UP_FORMAT, newline). org-w3ctr-metadata-timestamp-format drops ox-html’s %a weekday abbreviation (deliberate). org-w3ctr-home/up-format, a bare format string, is the natural *-function candidate. Special blocks: with user attributes org-w3ctr--special-block-builtin replaces the type class instead of concatenating it as ox-html does (class“user TYPE”=) — deliberate (explicit over implicit).
• Src-block feature gaps vs ox-html. Dropped when forking (judged low-value for W3C TR output). Revisit later:
  • Line numbers, coderef, retain-labels.
  • :html-wrap-src-lines and :html-klipsify-src.
  • Listing number in captions.
  • example-block fontification / line numbers.
  • Highlight engine: htmlize vs t-fontify-method + ef- slugs.
• Attr-reading machinery. The attribute helpers have grown several layers (t--read-attr__, t--make-attr__, t--make-attr__id, t--make-attr__id*, t--make-attr_html, t--make-attribute-string, t--src-block-attrs). Two syntaxes coexist (Lisp s-exprs for #+attr__, plists for #+attr_html). Candidates: a single intermediate representation or one canonical syntax.
• SVG global font cache. svg-by-mathjax uses fontCache: 'local'. MathJax’s fontCache: 'global' shares one <defs> per document (~1.9x smaller on a 100-formula sample). Tried and reverted; revisit if SVG output is kept.
• CSS cleanup in =assets/style.css=. Not urgent.
  • Dead rules: .org-center (never emitted).
  • .ef-* highlight colours lean dark-theme; provide light/dark pair.
  • pre > code.src invisible in dark theme; add dark-block override.
  • Inline src (t-inline-src-block) has no CSS; give it a style or drop the dead class.
• Src-block highlight backends. Today t-fontify-method is engrave or nil (server-side). Planned: further server-side backends, or client-side (e.g. highlight.js) by emitting bare <code class“language-LANG”>=.
• Special-block custom elements: a component cookbook. The :html-special-block-custom-elements registry (:template for Declarative Shadow DOM, :src and :script for the <head> scripts) is the declared seam for authoring W3C components, and that is where the mechanism stops: no org-special-block-extras- style block DSL (a defblock macro that =read=s the block header and =eval=s raw HTML) is planned. What belongs in the docs instead is a cookbook of correct component patterns for Org’s always block-level <p> light content: style :host and reset ::slotted(p) for inline components, wrap <slot> in a flow container for block components, route named slots with #+attr_html: :slot NAME, and choose :src vs :script. Theme through CSS custom properties (--w3c-*), and, as optional sugar, map a block’s :parameters (#+begin_x-badge :variant warn) onto element attributes.
• Caption policy across blocks. #+caption: parses on nearly every block – example-block, src-block, quote-block, verse-block, center-block, special-block, table, fixed-width, latex-environment, export-block, drawer – but only four have a consumer today: the standalone-image paragraph (<figure><figcaption>), the table (<caption>), the captioned src-block (a bare text node as the first child of its .example <div>), and the drawer (the caption reused as <summary>). Everything else drops the caption silently. W3C’s base.css splits a caption in two: the label and number come from a CSS counter on the container class (figcaption::before { content: "Figure " counter(figure) ". " }, .example::before gives “Example N”, and likewise .issue::before / .note::before), while the text is content the author supplies. So the back-end picks the container/class and emits the text, and must not compute numbers in Elisp – do not port ox-html’s org-export-get-ordinal / “Listing N:” machinery. Decide a mapping {element -> container/class -> caption home}, using W3C classes only (there is no .quote / .verse / .center counter):
  • figure (image paragraph) -> <figure><figcaption> (done).
  • table -> <caption> (done).
  • example-block / src-block -> .example <div>, caption text as the first child, i.e. the shape src-block already uses. example-block is already .example but never reads its caption: the smallest first cut, plus a helper shared with src-block.
  • the rest (quote, verse, center, special, fixed-width, latex-environment, export-block) have no W3C home; do not invent one – leave the caption dropped and say so.

  Pin the invariants while unifying: is the counter class applied only when captioned (src-block’s rule) or always (example-block’s)? And is the self-link anchor emitted on every captioned block or only src-block?

Non-goals

Explicitly out of scope for now.

• Dependency analysis. Charting how far ox-w3ctr leans on Org and mapping the internal t-* call graph. Final global-optimization and cleanup task.
• Cross-file link resolution (crossrefs). Resolving [[file:other.org::*Heading]] / ::#custom-id to an anchor in the target document, with a project-scoped persistent cache. Not now.
• Drop the =ox-publish= dependency. Replace org-publish-file-relative-name, org-publish-resolve-external-link, and org-publish-org-to with local implementations. Not now.
• Option validation. Checking user-supplied export options and customization variables for well-formedness. Options are trusted as given; the back-end verifies explicit markup only (attributes, block parameters), where malformed input fails loudly. Not now.