Puravida Extensions

Puravida Extensions

Install

Google Analytics

Google Analytics

Disqus

Collapsable

Copy blocks

Google Search

Ensure Https

Multi language

Each file

Calendar

Install

Google Analytics

Google Analytics

Disqus

Collapsable

Copy blocks

Callouts Tooltip

Google Search

Ensure Https

Multi language

Each file

Calendar

Maven

Gradle

Gradle

Example 1

Example 2

English

Spanish

Maven

Gradle

Gradle

Example 1

Example 2

English

Spanish

Example 1.1

Example 1.2

Example 2.1

Example 2.2

Example 2.3

Example 1.1

Example 1.2

Example 2.1

Example 2.2

Example 2.3

Some usefull (I hope) extensions to Asciidoctor

Algunas Extensiones de Asciidoctor que espero sean útiles

<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>

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'
}

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'
}

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>

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>

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:

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

example 1.2

example 2

example 2.1

example 2.2

example 2.3

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:

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>

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

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

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

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:

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:

11

salida Madrid 12:00

llegada Barcelona 18:00

12

salida Barcelona 14:30

17

Bird Watching

23

llegada Madrid 19:00