= Semantic HTML5 Backend For Asciidoctor
// custom
:gem-name: asciidoctor-html5s
:gh-name: jirutka/{gem-name}
:gh-branch: master

ifdef::env-github[]
image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.org/{gh-name}"]
image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
image:https://img.shields.io/npm/v/{gem-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{gem-name}"]
endif::env-github[]

This project provides alternative HTML5 converter (backend) for http://asciidoctor.org/[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 https://asciidoctor.org/docs/user-manual/#curved[“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).


[cols="2,^1l,3,^1l,^1"]
|===
| Name | Syntax | Languages (:lang:) | HTML | Rendered

.4+| double quotes
.4+| "`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”

.5+| single quotes
.5+| '`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 https://asciidoctor.org/docs/user-manual/#replacements[replacements table]: changes `--` to en dash and adds `---` for em dash.

[cols="2,^1l,^1l,^1,2"]
|===
| Name | Syntax | Unicode | Rendered | Notes

| En dash
| --
| –
| –
.2+| 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
| ---
| —
| —

|===


== 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 https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading#Images[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 https://github.com/slim-template/slim/[Slim] templates, but they are precompiled into pure Ruby code using https://github.com/jirutka/asciidoctor-templates-compiler/[asciidoctor-templates-compiler], so you don’t need Slim to use it!

ifndef::npm-readme[]
=== Ruby

* https://www.ruby-lang.org/[Ruby] 2.0+ or http://jruby.org/[JRuby] 9.1+
* https://rubygems.org/gems/asciidoctor/[Asciidoctor] 1.5.7+
* https://rubygems.org/gems/thread_safe/[thread_safe] (not required, but recommended for Ruby MRI)


=== Node.js
endif::npm-readme[]

* https://nodejs.org/[Node.js]
* https://www.npmjs.com/package/@asciidoctor/core[@asciidoctor/core] >=2.0.0 <2.2.0


== Installation

ifndef::npm-readme[]
=== Ruby

Install {gem-name} from Rubygems:

[source, sh, subs="+attributes"]
gem install {gem-name}

or to get the latest development version:

[source, sh, subs="+attributes"]
gem install --pre {gem-name}


=== Node.js
endif::npm-readme[]

Install {gem-name} from npmjs.com:

[source, sh, subs="+attributes"]
npm install --save {gem-name}


== Usage

ifndef::npm-readme[]
=== CLI

[source, sh, subs="+attributes"]
asciidoctor -r {gem-name} -b html5s FILE...


=== Node.js
endif::npm-readme[]

[source, js, subs="+attributes"]
----
// Load asciidoctor.js and {gem-name}.
const asciidoctor = require('@asciidoctor/core')()
const asciidoctorHtml5s = require('{gem-name}')

// 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 {gem-name}:

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 http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.