asciidoctor-html5s

asciidoctor-html5s copied to clipboard

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

ifdef::env-github[] image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22] 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

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

|===

== 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 <3.0.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.