asciidoctor-html5s
v0.5.1
Published
Semantic HTML5 backend (converter) for Asciidoctor
Downloads
43
Maintainers
Readme
This project provides alternative HTML5 converter (backend) for Asciidoctor 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” (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).
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: changes
--
to en dash and adds ---
for em dash.
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
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 templates, but they are precompiled into pure Ruby code using asciidoctor-templates-compiler, so you don’t need Slim to use it!
@asciidoctor/core >=2.0.0 <3.0.0
Installation
Install asciidoctor-html5s from npmjs.com:
npm install --save asciidoctor-html5s
Usage
// 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. For the full text of the license, see the LICENSE file.