asciidoctor-html5s

This project provides alternative HTML5 converter (backend) for [Asciidoctor](http://asciidoctor.org/) that focuses on correct semantics, accessibility and compatibility with common typographic CSS styles. Goals ----- - Clean markup with correct HTML5 semantics. - Good accessibility for people with disabilities. - Compatibility with common typographic CSS styles when possible and especially with GitHub and GitLab. - Full standalone converter without fallback to the built-in Asciidoctor converters. - Easy to use and integrate into third-party projects. - Well readable and maintainable code – this should be never sacrificed for performance (I’m looking at you, Asciidoctor!). Non-goals --------- - Compatibility with existing Asciidoctor CSS styles. Text Substitutions ------------------ ### Quotes Asciidoctor provides syntax for so-called [“curved quotation marks”](https://asciidoctor.org/docs/user-manual/#curved) (which are actually just the *correct* quotation marks), but the built-in converters outputs only one (hard-coded) type of the single/double quotation marks — that one used in English and few other languages. This converter outputs the correct type of the quotation marks based on the specified language (using standard `lang` attribute). <table> <colgroup> <col style="width: 25%" /> <col style="width: 12%" /> <col style="width: 37%" /> <col style="width: 12%" /> <col style="width: 12%" /> </colgroup> <thead> <tr class="header"> <th>Name</th> <th>Syntax</th> <th>Languages (:lang:)</th> <th>HTML</th> <th>Rendered</th> </tr> </thead> <tbody> <tr class="odd"> <td><p>double quotes</p></td> <td>"`word`"</td> <td><p>af, en, eo, ga, hi, ia, id, ko, mt, th, tr, zh</p></td> <td>&#x201c;word&#x201d;</td> <td><p>“word”</p></td> </tr> <tr class="even"> <td><p>bs, fi, sv</p></td> <td>&#x201d;word&#x201d;</td> <td><p>”word”</p></td> <td></td> <td></td> </tr> <tr class="odd"> <td><p>cs, da, de, is, lt, sl, sk, sr</p></td> <td>&#x201e;word&#x201c;</td> <td><p>„word“</p></td> <td></td> <td></td> </tr> <tr class="even"> <td><p>hu, pl, nl, ro</p></td> <td>&#x201e;word&#x201d;</td> <td><p>„word”</p></td> <td></td> <td></td> </tr> <tr class="odd"> <td><p>single quotes</p></td> <td>'`word`'</td> <td><p>af, en, eo, ga, hi, ia, id, ko, mt, th, tr, zh</p></td> <td>&#x2018;word&#x2019;</td> <td><p>‘word’</p></td> </tr> <tr class="even"> <td><p>bs, fi, sv</p></td> <td>&#x2019;word&#x2019;</td> <td><p>’word’</p></td> <td></td> <td></td> </tr> <tr class="odd"> <td><p>cs, da, de, is, lt, sl, sk, sr</p></td> <td>&#x201a;word&#x2018;</td> <td><p>‚word‘</p></td> <td></td> <td></td> </tr> <tr class="even"> <td><p>nl</p></td> <td>&#x201a;word&#x2019;</td> <td><p>‚word’</p></td> <td></td> <td></td> </tr> <tr class="odd"> <td><p>hu, pl, ro</p></td> <td>&#x00ab;word&#x00bb;</td> <td><p>«word»</p></td> <td></td> <td></td> </tr> </tbody> </table> The default (fallback) type is the first one. ### Replacements Asciidoctor replaces `--` with em dash (—) and does not provide any replacement for en dash (–). That’s not very convenient, because en dash is more common than em dash; at least in (British) English and Czech (actually we don’t use em dash at all). So this extension also modifies the [replacements table](https://asciidoctor.org/docs/user-manual/#replacements): changes `--` to en dash and adds `---` for em dash. <table> <colgroup> <col style="width: 28%" /> <col style="width: 14%" /> <col style="width: 14%" /> <col style="width: 14%" /> <col style="width: 28%" /> </colgroup> <thead> <tr class="header"> <th>Name</th> <th>Syntax</th> <th>Unicode</th> <th>Rendered</th> <th>Notes</th> </tr> </thead> <tbody> <tr class="odd"> <td><p>En dash</p></td> <td>--</td> <td>&#8211;</td> <td><p>–</p></td> <td><p>Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces.</p> <p>When flanked by space characters (e.g. <code>a -- b</code> or <code>a --- b</code>), the normal spaces are replaced by thin spaces (&#8201;).</p></td> </tr> <tr class="even"> <td><p>Em dash</p></td> <td>---</td> <td>&#8212;</td> <td><p>—</p></td> <td></td> </tr> </tbody> </table> Other Enhancements ------------------ ### Image Block The `link` attribute recognizes few special values: link=self Make the image a link with URL of the image itself – to open it in full size. link=none / link=false Suppress the effect of `:html5s-image-default-link: self`, i.e. remove the default image link. Both block image and inline image supports additional attribute `loading` (see [Lazy loading](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading#Images) on MDN for more information). ### Additional Inline Formatting Roles del `[del]#deleted text#` is rendered as `<del>deleted text</del>`. ins `[ins]#inserted text#` is rendered as `<ins>inserted text</ins>`. strike `[strike]#inserted text#` is rendered as `<s>inserted text</s>`. This is an alias for `line-through`. Requirements ------------ Note: This converter consists of [Slim](https://github.com/slim-template/slim/) templates, but they are precompiled into pure Ruby code using [asciidoctor-templates-compiler](https://github.com/jirutka/asciidoctor-templates-compiler/), so you don’t need Slim to use it! - [Node.js](https://nodejs.org/) - [@asciidoctor/core](https://www.npmjs.com/package/@asciidoctor/core) >=2.0.0 <3.0.0 Installation ------------ Install asciidoctor-html5s from npmjs.com: ``` sh npm install --save asciidoctor-html5s ``` Usage ----- ``` js // Load asciidoctor.js and asciidoctor-html5s. const asciidoctor = require('@asciidoctor/core')() const asciidoctorHtml5s = require('asciidoctor-html5s') // Register the HTML5s converter and supporting extension. asciidoctorHtml5s.register() // Convert the content to HTML using html5s converter. const content = "Hello, *world!*!" const html = asciidoctor.convert(content, { backend: 'html5s' }) console.log(html) ``` ### Attributes Extra attributes accepted by the asciidoctor-html5s: html5s-force-stem-type Ignore declared (e.g. `:stem: asciimath`, `asciimath:[]`, …) and default type of the stem macro/block and always use the one specified by this attribute. Asciidoctor hard-codes the default stem type to “asciimath”, which is not supported by KaTeX. html5s-image-default-link: self Make every block image a link with the image’s source URL (i.e. user can click on the image to open it in full size), unless the link attribute is defined and is not `none` or `false`. html5s-image-self-link-label The link title and ARIA label for the block image link that points to the image file (i.e. `href` equals the image’s `src`). Default is `Open the image in full size`. License ------- This project is licensed under [MIT License](http://opensource.org/licenses/MIT/). For the full text of the license, see the [LICENSE](LICENSE) file.