Skip to content

Commit a61c6d6

Browse files
ggrossetieggrossetie
committed
move entry to correct location
1 parent 339e2e6 commit a61c6d6

1 file changed

Lines changed: 1 addition & 4 deletions

File tree

‎CHANGELOG.adoc‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,13 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/main[co
88

99
== Unreleased
1010

11-
Improvements::
12-
13-
* Add a built-in *semantic HTML5* converter registered for the `semantic-html5` backend (`Asciidoctor.convert(input, { backend: 'semantic-html5' })`). *This backend is experimental*: it serves as the fast-iteration testbed for the modern HTML output effort started upstream in Asciidoctor's `feature/html-converter-next` branch (asciidoctor/asciidoctor#242) — its markup, class names and default stylesheet may change in any release without being treated as breaking changes, and it is not a candidate to replace the default `html5` backend; decisions validated here are meant to be ported back to the Ruby implementation. Unlike the default `html5` backend — whose output mirrors AsciiDoc.py for compatibility (wrapper `<div>`s, `class="paragraph"`, table-based admonitions, …) — this converter maximizes the use of semantic HTML constructs. It ports the work started in the upstream Ruby `feature/html-converter-next` branch (sections as `<section>`, bare `<p>` paragraphs, `<figure>`/`<figcaption>` for captioned listings and images, `<header>` with a `byline` and a revision `<table>`, `<time datetime>` for the revision date, `rel="author"` on author email links) and completes it with full node-type coverage: bare `<ul>`/`<ol>`/`<dl>` lists (captioned lists wrapped in `<figure>` with a `<figcaption>`), `<aside role="note">` admonitions (a non-landmark structuring role, per the accessibility consensus in the WHATWG `<callout>` element discussion — whatwg/html#10100 — with the three `:icons:` modes supported: text label, image icons honoring a per-block `icon` attribute, and `html5`-compatible Font Awesome markup), `<aside>` sidebars, `<blockquote>` quotes and verses with a `<footer>`/`<cite>` attribution, `<details>`/`<summary>` collapsible examples, `<figure class="example|literal|stem">` blocks, semantic `<table>`s (`<caption>`, `<colgroup>`, `halign-*`/`valign-*` classes only when non-default, no `tableblock` noise), consistently kebab-case class names (`sect-num`, `sect-level-1`, `no-wrap`, `single-quote`, `menu-seq`, `callout-num`, … instead of the legacy condensed `sectnum`/`nowrap`/`singlequote`/`menuseq`/`conum` spellings), a `<nav>` table of contents with nested `<ol>` outlines, footnotes as an `<ol>` inside `<section class="footnotes" role="doc-endnotes">` with `doc-noteref`/`doc-endnote`/`doc-backlink` ARIA roles, bare `<video>`/`<audio>`/`<iframe>` media elements (wrapped in `<figure>` when titled), `<hr class="page-break">` page breaks, and xref/ref/bibref inline anchors. The `icon:[]` macro, inline SVG embedding (`opts=inline`, including `data:` URI targets), interactive SVG `<object>`s, `link=self` and the `window`/`nofollow`/`noopener` link constraints on images, callout and checklist font/image icon modes, and per-cell `cellbgcolor` are supported like in the `html5` backend. Setting `htmlsyntax=xml` produces well-formed XML (self-closed void elements, expanded boolean attributes, XHTML namespace) so the output can be processed with an XML parser, XPath or XSLT (asciidoctor/asciidoctor#4309); the default HTML syntax uses clean HTML5 voids (no `/>`). Standalone (non-embedded) conversion produces a semantic page skeleton: `<header>`, `<main>` (holding the TOC, content and footnotes) and `<footer>` — no `id="content"` wrapper `<div>`s. The backend ships with its own default stylesheet, `asciidoctor-semantic.css` (the `html5` backend's `asciidoctor-default.css` targets a different structure and is never used): dependency-free system font stacks, automatic light/dark theming (`color-scheme` + `prefers-color-scheme` with `--asciidoctor-*` tokens), styling for every emitted class (admonition accents, TOC card, kbd keycaps, qanda/callout CSS counters, table frame/grid/stripes/alignment classes, responsive revision line) and print rules (real page breaks on `<<<`, `break-inside` guards, printed link URLs). It is embedded in standalone output by default, linked as `asciidoctor-semantic.css` with `:linkcss:`, omitted with `:stylesheet!:`, and replaced by a user `:stylesheet:`. The scenario-based test suite from the upstream branch is ported and extended (156 `.adoc`/`.html` fixture pairs in `test/fixtures/semantic-html5-scenarios/`). The converter class is exported as `SemanticHtml5Converter`, and the per-node element mapping and design rationale are documented in `devdocs/semantic-html5-converter.adoc`
14-
1511
Bug Fixes::
1612

1713
* Fix the warning issued when an asset cannot be found or read (e.g. `image::does-not-exist.svg[opts=inline]`) always reporting the document as `<stdin>`. The `docfile` attribute was looked up on the node instead of on the document, and since `docfile` is only ever set as a document attribute the lookup never resolved (https://github.com/asciidoctor/asciidoctor/issues/4873[asciidoctor#4873])
1814

1915
Improvements::
2016

17+
* Add a built-in *semantic HTML5* converter registered for the `semantic-html5` backend (`Asciidoctor.convert(input, { backend: 'semantic-html5' })`). *This backend is experimental*: it serves as the fast-iteration testbed for the modern HTML output effort started upstream in Asciidoctor's `feature/html-converter-next` branch (asciidoctor/asciidoctor#242) — its markup, class names and default stylesheet may change in any release without being treated as breaking changes, and it is not a candidate to replace the default `html5` backend; decisions validated here are meant to be ported back to the Ruby implementation. Unlike the default `html5` backend — whose output mirrors AsciiDoc.py for compatibility (wrapper `<div>`s, `class="paragraph"`, table-based admonitions, …) — this converter maximizes the use of semantic HTML constructs. It ports the work started in the upstream Ruby `feature/html-converter-next` branch (sections as `<section>`, bare `<p>` paragraphs, `<figure>`/`<figcaption>` for captioned listings and images, `<header>` with a `byline` and a revision `<table>`, `<time datetime>` for the revision date, `rel="author"` on author email links) and completes it with full node-type coverage: bare `<ul>`/`<ol>`/`<dl>` lists (captioned lists wrapped in `<figure>` with a `<figcaption>`), `<aside role="note">` admonitions (a non-landmark structuring role, per the accessibility consensus in the WHATWG `<callout>` element discussion — whatwg/html#10100 — with the three `:icons:` modes supported: text label, image icons honoring a per-block `icon` attribute, and `html5`-compatible Font Awesome markup), `<aside>` sidebars, `<blockquote>` quotes and verses with a `<footer>`/`<cite>` attribution, `<details>`/`<summary>` collapsible examples, `<figure class="example|literal|stem">` blocks, semantic `<table>`s (`<caption>`, `<colgroup>`, `halign-*`/`valign-*` classes only when non-default, no `tableblock` noise), consistently kebab-case class names (`sect-num`, `sect-level-1`, `no-wrap`, `single-quote`, `menu-seq`, `callout-num`, … instead of the legacy condensed `sectnum`/`nowrap`/`singlequote`/`menuseq`/`conum` spellings), a `<nav>` table of contents with nested `<ol>` outlines, footnotes as an `<ol>` inside `<section class="footnotes" role="doc-endnotes">` with `doc-noteref`/`doc-endnote`/`doc-backlink` ARIA roles, bare `<video>`/`<audio>`/`<iframe>` media elements (wrapped in `<figure>` when titled), `<hr class="page-break">` page breaks, and xref/ref/bibref inline anchors. The `icon:[]` macro, inline SVG embedding (`opts=inline`, including `data:` URI targets), interactive SVG `<object>`s, `link=self` and the `window`/`nofollow`/`noopener` link constraints on images, callout and checklist font/image icon modes, and per-cell `cellbgcolor` are supported like in the `html5` backend. Setting `htmlsyntax=xml` produces well-formed XML (self-closed void elements, expanded boolean attributes, XHTML namespace) so the output can be processed with an XML parser, XPath or XSLT (asciidoctor/asciidoctor#4309); the default HTML syntax uses clean HTML5 voids (no `/>`). Standalone (non-embedded) conversion produces a semantic page skeleton: `<header>`, `<main>` (holding the TOC, content and footnotes) and `<footer>` — no `id="content"` wrapper `<div>`s. The backend ships with its own default stylesheet, `asciidoctor-semantic.css` (the `html5` backend's `asciidoctor-default.css` targets a different structure and is never used): dependency-free system font stacks, automatic light/dark theming (`color-scheme` + `prefers-color-scheme` with `--asciidoctor-*` tokens), styling for every emitted class (admonition accents, TOC card, kbd keycaps, qanda/callout CSS counters, table frame/grid/stripes/alignment classes, responsive revision line) and print rules (real page breaks on `<<<`, `break-inside` guards, printed link URLs). It is embedded in standalone output by default, linked as `asciidoctor-semantic.css` with `:linkcss:`, omitted with `:stylesheet!:`, and replaced by a user `:stylesheet:`. The scenario-based test suite from the upstream branch is ported and extended (156 `.adoc`/`.html` fixture pairs in `test/fixtures/semantic-html5-scenarios/`). The converter class is exported as `SemanticHtml5Converter`, and the per-node element mapping and design rationale are documented in `devdocs/semantic-html5-converter.adoc`
2118
* Add an experimental build-time mode to the built-in `highlightjs` source highlighter, based on https://highlightjs.org[highlight.js]. Setting `:highlightjs-mode: build` colourises source blocks at conversion time on the server instead of shipping the hljs runtime for the browser to colourise; without the attribute the behaviour is unchanged (client-side), so no registration or extra setup is required. `highlight.js` is an *optional* `peerDependency`, loaded lazily on first use, so it is never bundled -- including in the browser build, where build mode is unsupported and the adapter falls back to client-side highlighting with a warning. Callouts, line numbering (`linenums`, both `table` and `inline` mode), `highlight=` line emphasis and `start=` are all supported. The theme stylesheet is read from the installed highlight.js package and embedded in a `<style>` tag by default (self-contained output); set `:highlightjs-stylesheet: link` to link the CDN instead, and `:highlightjs-theme:` to pick a theme (default `github`)
2219
* The syntax highlighter `highlight()` and `docinfo()` methods are now awaited by the core, so adapter implementations may be asynchronous (e.g. to load a highlighting library such as Shiki, or to read a stylesheet from disk, on demand). Existing synchronous adapters are unaffected since the returned value is awaited either way
2320

0 commit comments

Comments
 (0)