Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jirutka/asciidoctor-html5s

Semantic HTML5 converter (backend) for Asciidoctor
https://github.com/jirutka/asciidoctor-html5s

accessibility asciidoc asciidoctor asciidoctor-backend asciidoctor-converter html5 semantics

Last synced: 4 days ago
JSON representation

Semantic HTML5 converter (backend) for Asciidoctor

Awesome Lists containing this project

README 

          
= 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



| 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 `deleted text`.



ins::

  `++[ins]#inserted text#++` is rendered as `inserted text`.



strike::

  `++[strike]#inserted text#++` is rendered as `inserted text`.

  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] >=3.0.0 <4.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.