Some usefull (I hope) extensions to Asciidoctor
Algunas Extensiones de Asciidoctor que espero sean útiles
Install
Maven
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
....
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>bintray-puravida-software-repo</id>
<name>bintray</name>
<url>https://dl.bintray.com/puravida-software/repo</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>bintray-puravida-software-repo</id>
<name>bintray-plugins</name>
<url>https://dl.bintray.com/puravida-software/repo</url>
</pluginRepository>
</pluginRepositories>
<build>
<defaultGoal>process-resources</defaultGoal>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.maven.plugin.version}</version>
<dependencies>
<!-- Comment this section to use the default jruby artifact provided by the plugin -->
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>${jruby.version}</version>
</dependency>
<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
<!-- Add PuraVida Asciidoctor Extension -->
<dependency>
<groupId>com.puravida.asciidoctor</groupId>
<artifactId>asciidoctor-extensions</artifactId>
<version>${puravida.asciidoctor.version}</version>
</dependency>
</dependencies>
<configuration>
<sourceDirectory>src/docs/asciidoc</sourceDirectory>
</configuration>
<executions>
<execution>
<id>generate-html-doc</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<attributes>
<imagesdir>./images</imagesdir>
<toc>left</toc>
<icons>font</icons>
<sectanchors>true</sectanchors>
<idprefix/>
<idseparator>-</idseparator>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
....
</project>
Gradle
plugins {
id 'org.asciidoctor.jvm.convert' version '2.1.0'
}
repositories {
jcenter()
}
configurations {
asciidoctorExt
}
dependencies {
asciidoctorExt "com.puravida.asciidoctor:asciidoctor-extensions:${puravidaVersion}"
}
asciidoctorj{
version '2.0.0'
}
asciidoctor {
configurations 'asciidoctorExt'
}
Gradle
Añade el repositorio y las dependencias de PuraVida en Bintray en el fichero build.gradle
plugins {
id 'org.asciidoctor.jvm.convert' version '2.1.0'
}
repositories {
jcenter()
}
configurations {
asciidoctorExt
}
dependencies {
asciidoctorExt "com.puravida.asciidoctor:asciidoctor-extensions:${puravidaVersion}"
}
asciidoctorj{
version '2.0.0'
}
asciidoctor {
configurations 'asciidoctorExt'
}
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>
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>
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
Google Search
- 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:
Calendar
You can create a "calendar" table for an specific month specifying only the relevant events and this extension will render a table filling the gaps.
:icons: font
.Vacaciones 2019
[calendar,2019,1]
----
11 icon:bus[] salida Madrid 12:00
11 icon:bus[] llegada Barcelona 18:00
12 icon:plane[] salida Barcelona 14:30
15 icon:anchor[] Scuba
17 icon:binoculars[] Bird Watching
23 icon:car[] llegada Madrid 19:00
----
the extension will render as:
L | M | X | J | V | S | D |
---|---|---|---|---|---|---|
1 |
2 |
3 |
4 |
5 |
6 |
|
7 |
8 |
9 |
10 |
11 salida Madrid 12:00 llegada Barcelona 18:00 |
12 salida Barcelona 14:30 |
13 |
14 |
15 Scuba |
16 |
17 Bird Watching |
18 |
19 |
20 |
21 |
22 |
23 llegada Madrid 19:00 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |