Some usefull (I hope) extensions to Asciidoctor

Algunas Extensiones de Asciidoctor que espero sean útiles

Install

Maven

TODO!!

Gradle

Add PuraVida Bintray repository in your build.gradle and the dependencies

repositories {
    mavenCentral()
    // others
}
dependencies {
    asciidoctor "com.puravida-software.asciidoctor:asciidoctor-extensions:1.9.0-milestone.0.21+51cc885"
}

Gradle

Añade el repositorio y las dependencias de PuraVida en Bintray en el fichero build.gradle

repositories {
    mavenCentral()
    // others
}
dependencies {
    asciidoctor "com.puravida-software.asciidoctor:asciidoctor-extensions:1.9.0-milestone.0.21+51cc885"
}

Google Analytics

Simplemente usando el atributo google-analytics-code en la cabecera de tu documento, la extensión añadirá el código javascript necesario al final del documento HTML usando el código de Google Analytics que hayas especificado

Por ejemplo

= My document
Author
:doctype: book
:google-analytics-code: UA-000000-00

Generará

<!-- google -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-000000-00', 'auto');
ga('send', 'pageview');
</script>
Example 1. Questionario

Qué atributo usaremos si queremos añadir Google Analytics en nuestros docus

quizquestion:ga1es[10] google-analytics-code

quizquestion:ga1es[0] google_analytics_code

quizquestion:ga1es[0] ninguno, se incluye automaticamente

Example 2. Questionario

Cómo especificamos el código de Google Analytics

  • quizquestion:ga2es[0] Modificando el HTML generado manualmente

  • quizquestion:ga2es[10] cualificando el atributo google-analytics-code

  • quizquestion:ga2es[0] de ninguna forma, se incluye automaticamente

Qué atributo usaremos

quizzpoints:ga1es[]

Cómo especificar el código

quizzpoints:ga2es[]

quizztoolbar::[value="Validate"]

Google Analytics

If you put the attribute google-analytics-code in the header of your document it will render a javascript code at the end of the HTML with your Google Analytics code

= My document
Author
:doctype: book
:google-analytics-code: UA-000000-00
<!-- google -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-000000-00', 'auto');
ga('send', 'pageview');
</script>
Example 3. Question

What attribute you must to use if you want to include Google Analytics into your document

quizquestion:ga1en[10] google-analytics-code

quizquestion:ga1en[0] google_analytics_code

quizquestion:ga1en[0] it’s automatically include

Example 4. Question

How to specify the Google Analytics code

  • quizquestion:ga2en[0] editing the fina HTML

  • quizquestion:ga2en[10] setting a value to google-analytics-code

  • quizquestion:ga2en[0] it’s include automatically

What attribute is required

quizzpoints:ga1en[]

How specify the code

quizzpoints:ga2en[]

quizztoolbar::[value="Validate"]

Disqus

  • Open an account at https://disqus.com/ (if you haven’t yet)

  • Create a site, i.e. "asciidoctor-extensions"

  • Create a disqus inline block in your documentation with the name of your recently site created:

disqus::asciidoctor-extensions[] (1)
1 replace asciidoctor-extensions with you site

Here you can see the result:

Collapsable

= My document
Author
:doctype: book
:toc: left
:toclevels: 4
:toc-collapsable:

From version 1.4, if you have a large TOC (Table of Content) you can collapse it with the :toc-collapsable: document attribute.

In this version only sectlevel1 and sectlevel2 are considered.

Example 1

example 1

Example 1.1

example 1.1

Example 1.2

example 1.2

Example 2

example 2

Example 2.1

example 2.1

Example 2.2

example 2.2

Example 2.3

example 2.3

Copy blocks

From version 1.5, this extension adds the functionality to copy the content of blocks with IDs inserting a "copy" button above the block.

If you don’t want this functionality but you want to use others into this package you can disable it inserting the document attribute nocopyblocks

= My document
Author
:nocopyblocks:

Callouts Tooltip

From version 1.6, this extension adds the functionality to show a tooltip in every callout whith the corresponded text

This text has an explanation at the bottom (1)

But all of them, also has a tooptip (2)
1 If you have a lot of callouts the reader can be feel lost
2 But whit this tooltip he can read this text in the same place

If you don’t want this functionality but you want to use others into this package you can disable it inserting the document attribute notooltip

INFO

"Google Search can enable a rich set of features for your page in search results if it understands the content of the page and, in some circumstances, if you explicitly provide additional information in the page code using structured data." (https://developers.google.com/search/docs/guides/search-features)

This asciidoctor-extensions adds the capability to generate the structured data extracting from your document attribute.

First of all, you need to activate this functionality with the google-search document attribute:

:google-search:

If your document is a book doctype the final document will include something similar to:

 <script type = "application/ld+json" >
     {
         "@context": "http://schema.org",
         "@type": "Book",
         "name": "THE NAME OF YOUR DOCUMENT",
         "author": {
             "@type": "Person",
             "name": "THE NAME OF THE AUTHOR"
         }
     }
 </script>

In case doctype is article it will render something similar to:

 <script type="application/ld+json">
 {
   "@context": "http://schema.org",
   "@type": "Article",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://google.com/article"
   },
   "headline": "THE NAME OF YOUR DOCUMENT",
   "datePublished": "THE DATE OF YOUR DOCUMENT",
   "dateModified": "CURRENT DATE",
   "author": {
     "@type": "Person",
     "name": "THE NAME OF THE AUTOR"
   },
   "description": "THE PREFACE OF YOUR ARTICLE"
 }
 </script>

Ensure Https

If you want to be sure your HTML document it’s serve with Https protocol you need to add the attribute ensure-https

With this attribute the extension check if the user is using the version with the protocol http and in this case redirect the user to the https version, except if the server is localhost

Multi language

English

this extension is in alpha stage

If you have the same content but in different languages you must to write in different files the content and diferenciate them with some kind of filename extension. With the asciidoctor extension you can write in the same file all contents applying different roles to each paragrah and/or section.

You need to specify the document attribute :multilanguage: xx,yy,zz with and array of languages and them use this languages into your content.

If you want a "fixed" toolbar with language selector flags you need to specify the position with the :multilanguage-toolbar: document attribute using toc or header if you want to put under the Table of Content or under the Title

If you want to control where to put the toolbar you can use the macro multilanguage::toolbar[] wherever you want into your document.

For example:

= My multilanguage document
Jorge Aguilera
:toc: left
:toclevels: 4
:imagesdir: images
:multilanguage: gb,es,it

This parragrah will be always visible. Este párrafo será siempre visible

We want a toolbar / Queremos una barra de idiomas

multilanguage::toolbar[]

[role='language-gb']
This paragrah is writen in english and it'll be only visible if `language is equal to gb`

[role='language-es']
Este párrafo está escrito en español y solo será visible si `language vale es`


[role='language-it']
== Il Titolo

tutta questa sezione

sarà visibile solo

quando selezioni

l'italiano

[role='language-es']
== El titulo

toda esta seccion

será visible únicamente

cuando se seleccione

español

Spanish

Esta extensión se encuentra en desarrollo

Si tienes el mismo contenido a mostrar pero en diferentes idiomas normalmente los escribes en diferentes ficheros y los generas con diferentes nombres. Con esta extensión puedes escribir en el mismo fichero todo el contenido aplicando diferentes roles a cada párrafo o sección.

Simplemente añade el atributo :multilanguage: xx,yy,xx indicando un array de idiomas separados por comas y etiqueta las secciones y/o párrafos que quieres diferenciar con el idioma en el que están escrito.

Si quieres tener una barra de banderas para seleccionar el idioma en una posición fija puedes hacerlo con el atributo :multilanguage-toolbar: usando toc o header si quieres la barra en la sección de la Tabla de Contenidos o en el Título del documento.

Si por el contrario prefieres controlar donde ubicar la barra de herramientas puedes usar la macro language::toolbar[] en la parte del documento donde quieras que aparezca

Por ejemplo:

= My multilanguage document
Jorge Aguilera
:toc: left
:toclevels: 4
:imagesdir: images
:multilanguage: gb,es,it

This parragrah will be always visible. Este párrafo será siempre visible

We want a toolbar / Queremos una barra de idiomas

multilanguage::toolbar[]

[role='language-gb']
This paragrah is writen in english and it'll be only visible if `language is equal to gb`

[role='language-es']
Este párrafo está escrito en español y solo será visible si `language vale es`


[role='language-it']
== Il Titolo

tutta questa sezione

sarà visibile solo

quando selezioni

l'italiano

[role='language-es']
== El titulo

toda esta seccion

será visible únicamente

cuando se seleccione

español

Each file

If you have several files and want to do the same stuff with every one, but changing the name of the file, you must to repeat the same block several time. You can extract the "logic" to an extra asciidoctor file and use the include directive per every file but at the end you need to know the name of the files and write down in the document.

Sometimes these files are generated with and external process, they are the results of some test, etc and you don’t know the name of all of them but only the pattern they used (all of them are located in the same directory, they share the same extension, and so on).

With each-file block processor you define a template block with a qualifier and the processor repeat the template per each file who match the pattern.

Say we have some files with the pattern each-file-XXXX.txt and we want to include all of them into our documentation. Per every file we want to write a block with the same text and at the end include the file:

[each-file,pattern=each-file-(.).txt,sort=name]
++++
=== {filename}
Hi, I'm {filename} file
if you write this:
[source]
----
\include::{includedir}/{filename}[lines=1..100]
----
you obtain this:
\include::{includedir}/{filename}[lines=1..100]
++++

As arguments you can use:

  • pattern (required). A regular expression to apply to the name of the file

  • dir (optional). A path where search the files

  • sort (*optional) any of: name (default), date, size

  • order (optional) any of : asc (default) or desc

As you can see we use as the second argument the pattern of the files (each-file-1.txt, each-file-2.txt, …​ ) and we use in the block {filename} as a placeholder to write the real filename

Note that if you want to include every file you must to escape the include directive with and slash at the begining in order to avoid the preprocessor include a file with the name {filename}

Bellow you can see the result of the previous each-file block example:

Themes

If you want to change the style of your document you can set linkcss and stylesheet attributes and put the corresponding css files into stylesdir directory. But if you don’t want to deal with this files you can use our asciidoctor-themes extension and set the theme attribute you want to use.

  • include the extension

dependencies {
    asciidoctor "com.puravida.asciidoctor:asciidoctor-themes:1.9.0-milestone.0.21+51cc885"
}

  • set the theme you want to use in the header of your document:

= The Title
Your name
:theme: choose_one

The asciidoctor-themes come with differents themes prepackaged:

Quiz

If you want to offer to your reader a way to test if they understood your documentation you can insert quizzes into your document

Dependencies

Quiz is written in another artifact so firstly you must to include it into your dependencies

dependencies {
    asciidoctor "com.puravida.asciidoctor:asciidoctor-quizzes:1.9.0-milestone.0.21+51cc885"
}

Question

To add questions into your document you must to use the inline macro quizquestion

In order to be able to choose between options you must to specify the theme in the second part of the macro. As first attribute you must to specify how mucho points the answer has:

Groovy is a language similar to

quizquestion:languages[10,java] Java    (1) (2) (3)

quizquestion:languages[5,cplusplus] C++

Choose a prime number quizquestion:primes[1] 7, quizquestion:primes[0] 8, quizquestion:primes[10] 23 (4)
1 quizquestion is the macro id
2 languages group all questions with the same name in order to choose the selected
3 you must to assign points for each answer
4 another quiz called "primes" is created

Toolbar

To provide a way to validate answer we use quizztoolbar who render a toolbar (currently only a simple button)

quizztoolbar::[value="Validate"] (1)
1 Currently only value is allowed

Results

To provide a place where show the point obtained for every quiz we use quizzpoints. You can use this inline macro where you want (paragraphs, tables, etc), but pay attention to use the same id you selected for group answers

quizzpoints:theme[]  (1)
1 theme is the same id you use in quizquestion to group answwers

Example

If you want to test a full demo Quiz follow this quizzes/quiz1.html