Semantic HTML5 converter (backend) for Asciidoctor
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
data/templates
lib
src
test/examples
.editorconfig Import original HTML5/Slim templates from asciidoctor-backends Apr 13, 2015
.gitignore
.travis.yml Travis: Update deploy token for npmjs Aug 12, 2018
Gemfile
LICENSE
README.adoc
Rakefile
asciidoctor-html5s.gemspec
package.json

README.adoc

Semantic HTML5 Backend For Asciidoctor

Build Status Gem Version npm Version

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).

Name Syntax Languages (:lang:) HTML Rendered

double quotes

 "`word`"

af, en, eo, ga, hi, ia, id, ko, mt, th, tr, zh

 “word”

“word”

bs, fi, sv

 ”word”

”word”

cs, da, de, is, lt, sl, sk, sr

 „word“

„word“

hu, pl, nl, ro

 „word”

„word”

single quotes

 '`word`'

af, en, eo, ga, hi, ia, id, ko, mt, th, tr, zh

 ‘word’

‘word’

bs, fi, sv

 ’word’

’word’

cs, da, de, is, lt, sl, sk, sr

 ‚word‘

‚word‘

nl

 ‚word’

‚word’

hu, pl, ro

 «word»

«word»

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.

Name Syntax Unicode Rendered Notes

En dash

 --
 –

Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces.

When flanked by space characters (e.g. a -- b or a --- b), the normal spaces are replaced by thin spaces ( ).

Em dash

 ---
 —

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!

Installation

Ruby

Install asciidoctor-html5s from Rubygems:

gem install asciidoctor-html5s

or to get the latest development version:

gem install --pre asciidoctor-html5s

Node.js

Install asciidoctor-html5s from npmjs.com:

npm install --save asciidoctor-html5s

Usage

CLI

asciidoctor -r asciidoctor-html5s -b html5s FILE...

Node.js

// Load asciidoctor.js and asciidoctor-html5s.
const asciidoctor = require('asciidoctor.js')()
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.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.