Usando AsciiDoc e Asciidoctor para escrever documentação - Tutorial

Lars Vogel, Jennifer Nerlich (c) 2015-2020 vogella GmbHVersão 1.0,04/06/2018ÍNDICE

• 1. Introdução ao Asciidoc
• 2. Dicas de redação para ótimos documentos Asciidoc
• 3. Recursos básicos do documento
• 4. Conversão com Asciidoctor
• 5. Parágrafos e blocos de advertência para avisos, notas e dicas
• 6. Usando o IDE Eclipse como editor Asciidoc
• 7. Configurações para a saída de PDF
• 8. Gerando saída diferente para AsciiDoc
• 9. Recursos Asciidoc

Este tutorial contém algumas notas sobre como escrever documentação com AsciiDoc e Asciidoctor.

1. Introdução ao Asciidoc

1.1. O que é Asciidoc e Asciidoctor

AsciiDoc é um formato de documento de texto para escrever notas, documentação, artigos, livros, ebooks, apresentações de slides, páginas da web, páginas de manual e blogs. Os arquivos AsciiDoc podem ser traduzidos através do conjunto de ferramentas Asciidoctor para muitos formatos, incluindo HTML, PDF, EPUB, DocBook e página de manual. Qualquer editor de texto pode ser usado. Alguns sites, como o Github, renderizam arquivos AsciiDoc diretamente em HTML.

A lista a seguir é um exemplo de um arquivo Asciidoc simples.

= The First Asciidoc example: Subtitle                              
Lars Vogel(c) 2016 vogella GmbH                                     
Version 0.2, 17.12.2015                                             
:sectnums:                                                          
:toc:                                                               
:toclevels: 4                                                       
:toc-title: My Content                                              
                                                                    
:description: Example AsciiDoc document                             
:keywords: AsciiDoc                                                 
:imagesdir: ./img                                                   

This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.

== First section

Some text

== Second section

More test

1.2. Posição do TOC

Você pode definir a posição do toc.

:toc:
:toc: left
:toc: right
:toc: preamble

preamble posicionará o toc na área de conteúdo principal (alguns como padrão), mas antes do preable.

1.3. Instale o conjunto de ferramentas Asciidoctor

Se você quiser usar o Asciidoctor diretamente, você deve instalar seu conjunto de ferramentas. Se você estiver usando Gradle ou Maven como sistemas de construção, não é necessário instalar o Asciidoctor separadamente. O Gradle ou o Maven fornecem plug-ins para executar tarefas do Asciidoctor.

sudo apt-get install -y asciidoctor

2. Dicas de redação para ótimos documentos Asciidoc

2.1. Uma frase por linha

Tente escrever uma frase por linha. Isso permite que você pesquise esta frase facilmente e garanta que você use descrições concisas e fáceis de ler. Isso também torna mais fácil mover a frase em seu editor de texto favorito.

Com base na experiência pessoal, essa regra faz uma grande diferença no texto gerado. Ajuda a evitar estruturas de frases complexas e ajuda a reduzir a redundância em seu texto.

3. Recursos básicos do documento

3.1. Título

O título é definido na parte superior do arquivo .adoc como

= Title of the document

3.2. Subtítulo

Se você quiser definir um subtítulo, adicione um :(dois pontos seguidos de um espaço) após o título

= Title of the document: This is the subtitle

3.3. Autor

O autor pode ser escrito logo após o título com ou sem um atributo.

O autor também pode incluir informações como um e-mail ou uma URL entre colchetes angulares. É possível ter uma lista de autores. Vários autores e seus emails são separados por ponto e vírgula e um espaço ;.

Sem atributos:

= Title of the document: This is the subtitle
Jennifer Nerlich 

Com atributos:

= Title of the document: This is the subtitle
:author: Jennifer Nerlich
:email: jn@vogella.com

Asciidoctor usa o nome do autor e o e-mail para atribuir valores aos atributos embutidos que podem ser usados ​​em todo o corpo do documento. Esses atributos incluem: autor (nome e sobrenome), nome, sobrenome, nome do meio, iniciais e e-mail.

= Title of the document: This is the subtitle
Jennifer Nerlich 

My first name is {firstname}.

Se houver vários autores, você pode fazer referência a eles usando a seguinte convenção: {firstname2}, {firstname3}, etc.

3.4. Revisão

As informações de revisão estão listadas na terceira linha do documento .adoc, abaixo da linha de informações do autor com ou sem atributos. Pode incluir os seguintes dados:

• Número da revisão: deve conter pelo menos um caractere numérico. Letras ou símbolos que precedem o caractere numérico não serão renderizados. A menos que o atributo: version-label !: seja definido.
• Data de revisão
• Comentário de revisão

O número da revisão e a data da revisão são separados por um ,(vírgula e espaço). Comentário de revisão é separado por um :(dois pontos e espaço).

Sem atributos:

= Title of the document: This is the subtitle
Jennifer Nerlich 
v1.1, 15.05.2017: First draft

Com atributos:

= Title of the document: This is the subtitle
:revnumber: v1.1
:revdate: 15.05.2017
:revremark: First draft

3,5. Formatação de texto

Use o seguinte para destacar seu texto.

*This is bold text*

_This is cursiv text_

`This is mono text`

O resultado é o seguinte:

Este é um texto em negrito

Este é um texto cursiv

This is mono text

3,6. Forçar quebras de linha

Um + (mais) no final de uma linha com um espaço seguinte força uma quebra de linha.

++SPACE

3,7. Importar arquivos ou arquivo inclui

Você pode importar arquivos por meio da macro de inclusão. Isso também funciona para o código-fonte inclui. Para usar ---- em sua lista, use o estilo [lista] antes disso. O exemplo a seguir importa um arquivo formatado como código-fonte Java.

include::res/source.java[]

Resultado:

System.out.println("Hello");

3,8. Usando leveloffset

Por meio do leveloffsetatributo, você pode alterar o deslocamento da seção, por exemplo, uma =seção se tornará ==se você adicionar a seguinte instrução:

:leveloffset: 1.

Use a seguinte instrução para redefinir o deslocamento.

`:leveloffset: 0`

3,9. Importando arquivos parcialmente

Também é possível incluir arquivos parcialmente. Para isso, marque a parte do arquivo a ser incluída com uma tag como a seguinte:

//article.adoc
# tag::tagname[]
This should be included!
# end::tagname[]
This text will not be included!

e inclua o arquivo com o tagname entre colchetes como este:

include::article.adoc[tags=tagname]

O resultado seria

This should be included!

3,10. Importando imagens

Você pode importar imagens com image::a saída HTML, você pode adicionar o alttexto entre colchetes []. Se a imagem estiver localizada na imgpasta, a importação terá a seguinte aparência:

image::./img/vogellacompany.jpg[vogella Company]

:imagesdir: ./img
image::vogellacompany.jpg[vogella Company]

A importação de uma imagem com image::adicionará a imagem em uma nova linha. Se você quiser adicionar uma imagem embutida, use a macro:image:

This is just a text
image:vogellacompany.jpg[vogella Company, width=5%] to show inline images.

Resultado:

Este é apenas um texto

para mostrar imagens embutidas.

3,11. Usando diretivas condicionais

É possível incluir ou excluir texto com base nos atributos do documento ou com base no valor de um atributo do documento. Os atributos ifdef, ifndef e ifeval podem ser usados ​​para isso.

Para incluir conteúdo, se o atributo exercise_solutionfor definido, use a seguinte sintaxe:

ifdef::exercise_solution[]
Content is shown when test attribute is set
endif::exercise_solution[]

or

ifdef::exercise_solution[Content is shown when include attribute is set]

Para incluir conteúdo se o atributo exercise_solutionnão estiver definido, use a seguinte sintaxe:

ifndef::exercise_solution[]
Content is shown when test attribute is NOT set
endif::exercise_solution[]
OR
ifndef::test[Content is shown when test attribute is NOT set]

Também é possível usar vários atributos. Se os nomes dos atributos forem separados por uma ,(vírgula), apenas um dos atributos precisa ser definido para incluir o conteúdo. Se eles forem separados por um +(mais), todos os atributos devem ser definidos para incluir o conteúdo.

Com o atributo ifeval é possível avaliar o valor dos atributos. Se a expressão for verdadeira, o conteúdo está incluído no documento; caso contrário, não está.

:version: 1

ifeval::[{version} >= 1]
This is a good one!
endif::[]

ifeval::[{version} 

Neste caso, o texto Este é bom! será mostrado.

3,12. Definindo listas

As listas podem ser definidas com o operador * no início de uma linha. Você pode definir até 6 níveis para uma lista. Certifique-se de ter um espaço antes do elemento da lista. Exemplo:

Docker allows to package the full stack in a container:

* OS
** Windows
** Ubuntu
* JVM,
* App server
* Application with its configuration

Resultado:

• SO
  • janelas
  • Ubuntu
• JVM,
• Servidor de aplicativos
• Aplicativo com sua configuração

As listas numeradas começam com.

. OS
.. Windows
.. Ubuntu
. JVM,
. App server
. Application with its configuration

Resultado:

1. SO
   1. janelas
   2. Ubuntu
2. JVM,
3. Servidor de aplicativos
4. Aplicativo com sua configuração

Parágrafos, blocos, imagens, código-fonte, etc. adicionais são anexados a um elemento de lista, colocando um sinal de mais (+) em uma linha adjacente a ambos os blocos.

* Listing1
* Listing2
+
image::vote-asciidoc-issue.png[]

Resultado:

• Listagem 1
• Listagem 2

3,13. Menus e botões

Você pode definir menus e botões. Isso requer a ativação de um recurso experimental, por meio do atributo ** na seção de cabeçalho do seu documento.

menu:View[Zoom > Reset]

Press the btn:[OK] button when you are finished.

O resultado é semelhante ao seguinte.

Visão Ampliação Reiniciar .

aperte o Está bem botão quando você terminar.

3,14. Atalhos do teclado

Você também pode definir atalhos de teclado com a kbdmacro.

kbd:[Alt+F11] - Toggle Full Screen Mode in the Eclipse IDE

O resultado é o seguinte:

Alt+F11 - Alternar modo de tela inteira no IDE Eclipse

3,15. Imagens e gráficos

Para referenciar imagens em seu AsciiDoc com a image::macro apontando para um local de arquivo relativo. Use colchetes para definir um tamanho fixo ou relacionado.

image::vogellacompany.jpg[200,200]

O resultado é o seguinte:

Você também pode definir um texto para a imagem que é, por exemplo, usado para leitores de tela ou como espaço reservado se a imagem não puder ser encontrada.

image::vogellacompany.jpg[vogella Logo, 200,200]

Se você deseja dimensionar a imagem para a saída em PDF, você pode usar o pdfwidthatributo.

image::vogellacompany.jpg[vogella Logo,pdfwidth=40%]

3,16. Usando ícones embutidos

Você também pode adicionar a diretiva `font` no topo do seu documento, o que permite usar os ícones do diretório http://fortawesome.github.io/Font-Awesome/icons/ por meio de um marco.

icon:comment[] This is a comment icon

icon:file[] And a file icon

icon:battery-full[] And a battery icon

O resultado é semelhante ao seguinte

Este é um ícone de comentário

E um ícone de arquivo

E um ícone de bateria

3,17. Definindo links externos

A Asciidoc determina links automaticamente no conteúdo do seu documento, se o link começar com http: // ou https: //. Você também pode definir um texto âncora via [] diretamente após o link.

http://www.vogella.com[vogella]

http://www.vogella.com

O resultado é semelhante ao seguinte.

vogela

http://www.vogella.com

Para incluir um link com espaços em branco ou caracteres especiais como por exemplo

https://vogella.com--sa- 23345

a definição deve ser semelhante a esta:

link:++https://vogella.com--sa- 23345++

3,18. Definindo referências cruzadas

Você pode atribuir metadados a um bloco. Aqui está um exemplo de um bloco de cotação que inclui todos os tipos de metadados:

.Topic Titel                                   
[[yourId]]                                     
[yourstyle]                                    
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure.
____

Você pode fazer um link para as referências por meio de, por exemplo. Você encontrará mais informações sobre isso em [yourId] .

3,19. Mesa

Você também pode criar tabelas no Asciidoc por meio da seguinte sintaxe.

.This is the optional title of the table
|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===

O resultado é semelhante ao seguinte.

Tabela 1. Este é o título opcional da tabela

Você também pode definir a largura relativa da tabela.

.with relative column widths (1,3)
[cols="1,3",options="header"]
|===
| Name | Description
| Testing
| Table width
|===

Claro que você pode definir tabelas com mais de duas colunas.

.Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===

3.19.1. Definir larguras de coluna

A [cols="1,3"]declaração diretamente abaixo do .declaration pode ser usada para especificar a largura da coluna. Se a largura for definida, a opção = "cabeçalho" também deve ser definida assim: [cols = "1,3", options = "cabeçalho"] para ver a primeira linha de uma tabela como um cabeçalho.

.Title
[cols="1,3",options="header"]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===

O snippet acima resultará no seguinte:

Tabela 2. Título

Alternativamente, os valores de% podem ser usados, por exemplo, [cols = "40%, 60%"].

Para adicionar elementos asciidoc especiais como listas, notas, código fonte, etc. dentro de uma célula de tabela, basta adicionar um aantes de |. Alguns elementos como atalhos de teclado (kbd) e botões (btn) não precisam de uma definição especial nas tabelas. Isso ficaria assim:

.with asciidoc elements
|===
|Keyboard shortcut |List |Note |Button

|kbd:[Ctrl+9]
a|* Test 1
* Test 2
* Test 3
a|
[NOTE]
====
This is a good idea
====
|btn:[OK]

|===

Tabela 3. com elementos asciidoc

3,20. Código-fonte e usando monoespaço

Use a formatação de texto monoespaçada para emular como o código-fonte aparece em terminais de computador, editores de texto simples e ambientes de desenvolvimento integrado (IDEs). Envolva a string hipthen inicial com \ para isso, por exemplo, `System.out.println (" Hello ");` resulta emSystem.out.println("Hello");

Para habilitar o destaque de sintaxe na saída, defina o estilo no bloco como source e especifique o idioma de origem na segunda posição do atributo. Os estilos de realce possíveis são descritos no capítulo Realce do código-fonte .

include::res/test.java

Os idiomas suportados dependem do seu renderizador, mas você pode, por exemplo, usar:

• console - para saída de terminal
• java - para arquivos de origem Java

3.20.1. Frases de destaque

Também é muito simples adicionar textos explicativos, conforme demonstrado pelo seguinte trecho. Você pode usar . para numerar automaticamente os textos explicativos.

System.out.println ("Olá"); # <.>
private int a;
<.> Importa a biblioteca</.></.>

O resultado é o seguinte

System.out.println("Hello");  
private int a;

Os tipos suportados são java, xml, terminal

3.20.2. Destaque do código fonte

O realce de sintaxe pode ser usado definindo o atributo source-highlighter no cabeçalho do documento.

:source-highlighter: pygments

As opções válidas para estilos html são coderay, highlightjs, prettify e pygments. Para coderay de estilo pfd, rouge e pigmentos estão disponíveis.

coderay, rouge e pygments funcionam com um estilo css incorporado que será adicionado à pasta do arquivo * .adoc durante a conversão de saída. Neste caso, o atributo include::../10_Include/settings.adoc[]deve ser definido no cabeçalho do documento. destaquejs e prettify usam javascript.

Para pigmentos, realce, ressalte que há uma variedade de estilos / temas diferentes.

Para usar um estilo de pygement, adicione o seguinte atributo ao cabeçalho do documento:

:pygments-style: xcode

Se você não definir o atributo de estilo de pygement, o estilo padrão será usado.

Para ver a lista de todos os estilos de pigmentos disponíveis, execute: pygmentize -L stylesna linha de comando.

Quanto aos hightlightjs, os estilos são chamados de temas e podem ser adicionados ao cabeçalho do documento da seguinte forma:

:highlightjs-theme: xcode

3,21. Sinalização especial de fuga

Se você precisar escapar dos comandos do Asciidoc, pode usar \antes do caractere que normalmente seria interpretado pelo Asciidoc. Para escrever, por exemplo, |você precisa escrevê-lo como este: \|.

3,22. Índice

Você pode adicionar termos de índice primário ao seu documento via (((yourterm))). Um índice secundário pode ser adicionado ao seu documento via (((seu termo, termo secundário 2))). Por exemplo:

((((Gatos grandes)))

(((((Gatos grandes, leões)))

3,23. Comentários no Asciidoc

Você pode adicionar comentários à marcação Asciidoc. Os comentários não são adicionados à saída gerada. Você pode usar comentários simples e multilinhas. Comentários de linha única começam com uma barra dupla (//). Os comentários de várias linhas são colocados em um bloco de quatro barras (////).

3,24. Marcação de escape Asciidoc

A maioria dos elementos AsciiDoc podem ser escapados precedendo-os com um caractere de barra invertida.

3,25. Atributos / variáveis ​​personalizadas

Você pode definir variáveis ​​personalizadas e usá-las em seu documento. Por exemplo, o seguinte define a variável yourvariableque pode ser usada com {sua variável} e Asciidoctor irá substituí-la com o valor definido após o segundo:.

:yourvariable: vogella

3,26. Elementos recolhíveis

AsciiDoc suporta o elemento nativo para ocultar elementos e torná-los disponíveis ao clicar.

.Title
[%collapsible]
====
Normal asciidoc markup here
====

Título

4. Conversão com Asciidoctor

Você precisará de uma instalação do Ruby em funcionamento. Para nosso guia de instalação, consulte: https://www.vogella.com/tutorials/Ruby/article.html

4.1. Instalação do Asciidoctor

Para converter seus arquivos asciidoc, você precisa instalar a gem Asciidoctor .

gem install asciidoctor

Se você deseja criar arquivos pdf, pode usar a gem asciidoctor-pdf.

gem install --pre asciidoctor-pdf

4.2. Convertendo AsciiDoc em html5

Como o Asciidoctor será padronizado para o backend html5, você não precisa chamá-lo com nenhum argumento extra.

asciidoctor example.adoc
# defaults to
asciidoctor -b html5 example.adoc

Para ver uma lista de todos os back-ends disponíveis, você pode chamar asciidoctor --help.

4.3. Convertendo AsciiDoc em arquivos PDF

Após a instalação das joias, você está pronto para converter seus arquivos AsciiDoc para o formato pdf.

asciidoctor-pdf example.adoc

4,4. Usando a versão de desenvolvimento do Asciidoctor para criar arquivos PDF

Se você quiser usar a última versão de desenvolvimento do asciidoctor para criar seus arquivos pdf, você tem que clonar o repositório asciidoctor-pdf do Github.

git clone git@github.com:asciidoctor/asciidoctor-pdf.git

Para preparar o aplicativo, primeiro você precisa instalar as dependências. Você pode ter que instalar o bundler gem primeiro.

cd asciidoctor-pdf
bundle install

Agora você pode começar a usar a versão mais recente para converter seu AsciiDoc.

./bin/asciidoctor-pdf /path/to/your/file.adoc
# or via bundler
bundle execute asciidoctor-pdf /path/to/your/file.adoc

4.5. Usando Asciidoctor em um arquivo de compilação do Gradle

4.5.1. Usando AsciidoctorJ em uma versão do Gradle

A maneira mais fácil de usar o Asciidoctor em uma compilação do Gradle é por meio do plug-in Asciidoctor Gradle. É baseado no AsciidoctorJ, que funciona como um wrapper Java para o Asciidoctor.

O exemplo a seguir build.gradleconverterá seus arquivos de origem em html5.

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
}

apply plugin: 'java'
apply plugin: 'org.asciidoctor.convert'

asciidoctorj {
    version = '1.5.4'
}

asciidoctor {
    attributes \
        'build-gradle': file('build.gradle'),
        // point this to the folder that holds your AsciiDoc
        'sourcedir': project.sourceSets.main.java.srcDirs[0],
        'endpoint-url': 'http://example.org',
        'source-highlighter': 'coderay',
        'imagesdir': 'images',
        'toc': 'left',
        'icons': 'font',
        'setanchors': '',
        'idprefix': '',
        'idseparator': '-',
        'docinfo1': ''
}

Você inicia a conversão invocando a asciidoctortarefa.

gradle asciidoctor

4.5.2. Usando a gema Asciidoctor-Pdf em uma versão do Gradle

Você pode usar a versão Ruby mais recente das extensões Asciidoctor diretamente em sua compilação do Gradle. O exemplo a seguir mostra como usar a gem asciidoctor-pdf.

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
    id 'com.github.jruby-gradle.base' version '1.3.3'
}

apply plugin: 'org.asciidoctor.convert'

dependencies {
    gems 'rubygems:asciidoctor-pdf:1.5.0.alpha.13'
}

asciidoctorj {
    version = '1.5.4.1'
}

asciidoctor {
    // jrubyPrepare downloads and installs Ruby Gem dependencies
    dependsOn jrubyPrepare
    // include the 'asciidoctor-pdf' Ruby module
    requires = ['asciidoctor-pdf']
    // let the Asciidoctor Plugin search for Gems in jrubyPrepares output directory
    gemPath = jrubyPrepare.outputDir
    // convert to pdf
    backends 'pdf'
}

Você inicia a conversão invocando a asciidoctortarefa.

gradle asciidoctor

4.5.3. Usando a versão de desenvolvimento do Asciidoctor-Pdf em um arquivo de compilação do Gradle

Para usar a versão de desenvolvimento do Asciidoctor-Pdf em um arquivo de compilação do Gradle, primeiro você precisa compilar a gema.

git clone git@github.com:asciidoctor/asciidoctor-pdf.git
cd asciidoctor-pdf
bundle
bundle exec rake build

Você pode então encontrar o .gemarquivo em /pkg. Copie-o em seu projeto Gradle na pasta development-gems.

Vamos usar o plugin JRuby e Asciidoctor Gradle, então precisamos declará-los.

plugins {
  id 'org.asciidoctor.convert' version '1.5.3'
  id 'com.github.jruby-gradle.base' version '1.3.3'
}

apply plugin: 'org.asciidoctor.convert'

Para usar uma gema local do Gradle, todas as dependências dessa gema devem ser especificadas manualmente. Você pode encontrar as dependências emasciidoctor-pdf.gemspec

Gem::Specification.new do |s|
  # ...
  s.add_runtime_dependency 'prawn', '>= 1.3.0', '
  s.add_runtime_dependency 'prawn-table', '0.2.2'
  s.add_runtime_dependency 'prawn-templates', '0.0.3'
  s.add_runtime_dependency 'prawn-svg', '>= 0.21.0', '
  s.add_runtime_dependency 'prawn-icon', '1.3.0'
  s.add_runtime_dependency 'safe_yaml', '~> 1.0.4'
  s.add_runtime_dependency 'thread_safe', '~> 0.3.5'
  s.add_runtime_dependency 'treetop', '1.5.3'
end

Você pode então adicioná-los ao seu build.gradle.

dependencies {
  gems 'rubygems:prawn:2.1.0'
  gems 'rubygems:prawn-table:0.2.2'
  gems 'rubygems:prawn-templates:0.0.3'
  gems 'rubygems:prawn-svg:0.25.2'
  gems 'rubygems:prawn-icon:1.3.0'
  gems 'rubygems:safe_yaml:1.0.4'
  gems 'rubygems:thread_safe:0.3.5'
  gems 'rubygems:treetop:1.5.3'
}

Você precisa substituir a tarefa jrubyPrepare para usar todas as dependências declaradas mais a gem local.

import com.github.jrubygradle.JRubyPrepare
task customJRubyPrepare(type: JRubyPrepare) {
  dependencies project.configurations.gems
  dependencies file('development-gems/asciidoctor-pdf-1.5.0.alpha.14.dev.gem')
  outputDir buildDir
}

Finalmente, você deve certificar-se de que a tarefa do asciidoctor depende customJRubyPreparee exige asciidoctor-pdf.

asciidoctor {
    dependsOn customJRubyPrepare
    requires ['asciidoctor-pdf']
    gemPath customJRubyPrepare.outputDir
    backends 'pdf'
}

Acione a tarefa asciidoctor para converter seu AsciiDoc.

gradle asciidoctor

5. Parágrafos e blocos de advertência para avisos, notas e dicas

5.1. Parágrafos de advertência

Um parágrafo de advertência chama a atenção do leitor para certas informações. Ele pode ser definido por uma etiqueta predefinida no início do parágrafo ou como um bloco.

Here are the other built-in admonition types:

NOTE: Some additional info...

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...

O resultado é o seguinte:

Aqui estão os outros tipos de advertência integrados:

5,2 Blocos de advertência

Você também pode usar blocos de advertência.

[TIP]
====
Think of c1..c2 as _all commits as of c1 (not including c1) until commit
c2._
====

A saída é semelhante à seguinte.

Semelhante a uma dica, você pode adicionar um aviso.

[WARNING]
====
This is a warning
====

A saída é semelhante à seguinte.

Os seguintes estilos são suportados:

• NOTA
• DICA
• IMPORTANTE
• CUIDADO
• ATENÇÃO

Você também pode adicionar cabeçalho a essas admoestações.

.My header for the note
[NOTE]
====
Blabla
====

Isso se parece com o seguinte:

5,3. Citações em bloco

[quote, Ben Parker, Spiderman Movie]
____
With great power comes great responsibility.
____

será parecido com isto:

Com grandes poderes vem grandes responsabilidades.

- Ben ParkerFilme do homem aranha

6. Usando o IDE Eclipse como editor Asciidoc

Atualmente, o melhor plug-in de editor Asciidoc para Eclipse IDE é fornecido por https://github.com/de-jcup/eclipse-asciidoctor-editor .

Você pode instalá-lo por meio de sua entrada no Marketplace: https://marketplace.eclipse.org/content/asciidoctor-editor

Ele fornece um editor e uma guia de visualização para o Asciidoc.

Um recurso interessante é que, se você segurar a tecla CTRL (tecla Command no Mac), poderá abrir os arquivos incluídos na include::diretiva.

7. Configurações para a saída de PDF

7.1. Folha de rosto

A página de título de um documento PDF pode incluir os seguintes atributos:

• Título
• Subtítulo
• Autor
• Revisão

Esses atributos podem ser estilizados no arquivo basic-theme.yml na pasta themes .

7.2. Links

Para ver os links na saída gerada, use o seguinte atributo no cabeçalho do seu documento.

:show-link-uri:

Além disso, você pode configurar o rótulo de um capítulo por meio do chapter-labelatributo, por exemplo, se não quiser nenhum rótulo, você pode usar:

:chapter-label:

Infelizmente, o Asciidoctor não adiciona uma quebra de página antes de uma parte se você usar "livro" como saída. Consulte https://github.com/asciidoctor/asciidoctor-pdf/issues/329 . Como solução alternativa, você deve colocar quebras de linha manuais nele com .

7.3. Índice

Você pode adicionar um índice à sua saída de PDF definindo-o da seguinte maneira:

[index]
= Index

Isso listará todos os índices definidos. A saída será semelhante a esta:

7,4 Apêndice

O apêndice é definido da seguinte forma:

[appendix]
= Appendix

7,5. Definir o estilo da saída PDF

Para definir o estilo da saída do PDF, use o arquivo basic-theme.yml na pasta themes . Neste arquivo você pode estilizar a página de título, os cabeçalhos (h1, h2, h3, etc), as imagens e muitos outros objetos.

Por exemplo, para estilizar o título, faça a seguinte entrada no arquivo basic-theme.yml :

heading:
  font_style: bold
  h1:
    font_color: 999999
    font_style: italic
    align: right

Um recurso útil é definir uma largura padrão para imagens na saída de PDF. Para conseguir isso, faça a seguinte entrada:

image:
  width: 60%

Para ver todas as configurações de estilo possíveis, visite o guia de temas Asciidoc .

7,6. Modo de Publicação

Para usar alguns atributos de publicação, você deve definir o mediaatributo no cabeçalho do seu documento AsciiDoc da seguinte maneira:

:media: prepress

Este atributo irá acionar as seguintes configurações:

• Margens da página frente e verso (espelho)
• Páginas opostas automáticas

7.6.1. Margens da página frente e verso (espelho)

As margens dos dois lados da página terão o seguinte impacto: as margens da página para as páginas recto (direita, número ímpar) e verso (lado esquerdo, número par) serão substituídas pelas margens laterais da página com os valores das chaves page_margin_inner e page_margin_outer.

Você pode definir o page_margin_inner e o page_margin_outer no tema. Isso terá a seguinte aparência:

page:
  margin: [0.5in, 0.67in, 0.67in, 0.67in]
  margin_inner: 0.75in
  margin_outer: 0.59in

Essas configurações irão acionar a seguinte mudança na saída:

recto page margin
[0.5in, 0.59in, 0.67in, 0.75in]

verso page margin
[0.5in, 0.75in, 0.67in, 0.59in]

7.6.2. Páginas opostas automáticas

Em relação às páginas opostas automáticas, uma página em branco será inserida, se necessário, para garantir que as seguintes páginas sejam páginas diretas:

• Folha de rosto
• Índice
• Primeira página do conteúdo do corpo
• Partes e capítulos

É possível desativar o recurso de faceamento automático para uma determinada parte ou capítulo. Isso pode ser feito adicionando a opção nonfacing [% nonfacing] ao nó de seção. Quando a opção sem rosto está presente, o título da parte ou do capítulo será colocado na página seguinte.

[%nonfacing]
= Chapter Title

Chapter content

8. Gerando saída diferente para AsciiDoc

8,1 Usando modelos personalizados para alterar a saída html

O estilo padrão da ferramenta asciidoctor é bom para a maioria dos casos. Mas alguns casos requerem o uso de modelos personalizados para modificar a saída para o caso de uso.

Isso requer a especificação da opção template_dirno arquivo de configuração.

Para gradle:

options template_dirs : [new File('').absolutePath]

Para o conjunto de ferramentas Asciidoctor CLI, use o parâmetro -T:

$ asciidoctor -T ''

Os modelos podem ser escritos em haml ou slim.

8,2. Converter para DocBook

Para converter asciidoc em DocBook, use o seguinte comando:

asciidoctor -b docbook45 inputfile.adoc.

8,3. Incluir conteúdo no cabeçalho de nossa saída HTML ou Docbook

Você pode adicionar conteúdo ao cabeçalho da saída HTML. Consulte http://asciidoctor.org/docs/user-manual/#docinfo-file para obter detalhes.

9. Recursos Asciidoc

Página de suporte para AsciiDoc

AsciiDoc homepage

Guia do redator AsciiDoc

Como definir um índice no Asciidoc

Manual do Eclipse [tecnologias usadas, incluindo Asciidoc

DocBook para ferramenta de conversão Asciidoc

Vídeo do Youtube sobre como escrever documentação com Asciidoctor

Asciidoctor com exemplo do Gradle

Plugin Eclipse para Asciidoc

AsciiDoc Gradle plug-in de documentação s

Awesome Asciidoctor: Auto Number Callouts