Unverified Commit 1aabe6f9 authored by Thomas Bouffard's avatar Thomas Bouffard Committed by GitHub
Browse files

doc: use 'AsciiDoc' wording instead of 'Asciidoctor' when appropriate (#252)

parent 151aaf12
......@@ -9,7 +9,7 @@ ifdef::env-github[]
endif::[]
// External URIs:
:url-antora: https://antora.org
:url-asciidoctor: https://asciidoctor.org/
:url-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation
......@@ -19,7 +19,7 @@ image::https://api.netlify.com/api/v1/badges/df65c069-bb52-46d2-8bf0-8e16b6b2148
*_DISCLAIMER: this is a work in progress._*
This repository let you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoctor}:[Asciidoctor]
This repository let you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoc}:[AsciiDoc]
documentation content stored in various Git repositories.
......
......@@ -11,5 +11,5 @@
* xref:architecture.adoc[Architecture Overview]
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
* migration from the old documentation site (archives)
** xref:./migrate-from-old-documentation-site/doc-content-conversion-from-md-to-adoc.adoc[Convert markdown content to asciidoctor]
** xref:./migrate-from-old-documentation-site/doc-content-conversion-from-md-to-adoc.adoc[Convert markdown content to AsciiDoc]
** xref:./migrate-from-old-documentation-site/migration-steps-put-the-site-live.adoc[Migration to put the site live]
......@@ -11,7 +11,7 @@ Antora is a multi-repository documentation site generator.
The Antora playbook is configured by the file _antora-playbook.yml_. +
This configuration file lists all the components, and the branches to build. It also references the UI bundle and some additional Asciidoctor extensions, both used to generate the HTML.
The Antora generator retrieves Asciidoctor sources from our documentation content repositories, and then generate a static HTML website from those sources.
The Antora generator retrieves AsciiDoc sources from our documentation content repositories, and then generate a static HTML website from those sources.
[NOTE]
====
......
......@@ -88,7 +88,7 @@ Example of embedded asciinema recording:
++++
----
The generated asciidoctor (before transformation by Antora) document should render like something like this:
The generated AsciiDoc (before transformation by Antora) document should render like something like this:
[.thumb]
image::images/asciinema_sample_rendering.png[]
......@@ -142,9 +142,9 @@ Use `{bonitaVersion}` syntax to reference this attribute in content. It will be
==== Disabling attribute substitution
Any elements around braces are interpreted as attribute and so, Asciidoctor tries to substitute them. If the value around braces is not related to
Any elements around braces are interpreted as attribute and so, they will be substitued in the generated output. If the value around braces is not related to
a declared attributes, warnings are emitted when generating the html files. +
For instance, in `+${CATALINA_HOME}/conf/jaas.cfg+`, Asciidoctor tries by default to substitute `CATALINA_HOME` which is not something we want
For instance, in `+${CATALINA_HOME}/conf/jaas.cfg+`, `CATALINA_HOME` is substituted by default which is not something we want
as we want to document an example with bash substitution.
To disable attribute substitution in inline text, add a `+` character around the text that contains the braces
......
= Documentation content conversion steps
:icons: font
The following describes how to convert content repository branch from Markdown for the old documentation site to Asciidoctor
The following describes how to convert content repository branch from Markdown for the old documentation site to AsciiDoc
for the new documentation site using Antora.
The steps describe here are supposed to be followed in the order they appear.
......@@ -34,7 +34,7 @@ Clean files
* README.md: everything can be removed except the title. This needs rework as part of https://github.com/bonitasoft/bonita-documentation-site/issues/52[#52]
== Markdown to Asciidoctor conversion
== Markdown to AsciiDoc conversion
=== Tool installation
......@@ -55,7 +55,7 @@ Sources (markdown and images files) are stored in the `md` folder of the documen
[CAUTION]
====
The index page generally contains html elements that cannot be automatically converted (some other pages way also be impacted). +
There is also a dependency on font-awesome css (`fa-` directives). Font awesome support is available in Asciidoctor
There is also a dependency on font-awesome css (`fa-` directives). Font awesome support is available in AsciiDoc.
For such a page, the html part must be commented prior running conversion otherwise the process fails.
====
......@@ -71,8 +71,8 @@ From the root of the old documentation folder, run the following command
.The script will :
[info]
* Sanitize the markdown source files to make theme convertible (update syntax).
* Convert md files to asciidoctor using kramdoc
* Sanitize the asciidoctors files generated
* Convert md files to AsciiDoc using kramdoc
* Sanitize the AsciiDoc files generated
** Convert custom 'Bonita' tags for notes, warnings, ....
[Exemple]
For instance:
......@@ -86,7 +86,7 @@ In each file you should get update like this:
image::images/doc_anchor_conversion.png[]
* Rename Asciidoctor files and remove old markdown files
* Rename AsciiDoc files and remove old markdown files
=== Final steps
......
......@@ -18,7 +18,7 @@ CAUTION: keep for archives
Everything is done at branch management level
* all existing branches must be kept untouched as they are used by the old doc site solution
* we are creating new branches based on the existing ones, then xref:doc-content-conversion-from-md-to-adoc.adoc[convert the content from markdown to asciidoctor]
* we are creating new branches based on the existing ones, then xref:doc-content-conversion-from-md-to-adoc.adoc[convert the content from markdown to AsciiDoc]
* for `out-of support version` branch: we can convert the branch while developing the new documentation site. The branch for out-of-support version are no more updated
* for `supported version` branch: they have to be converted for testing, need to be removed prior the actual migration
* at least some of them to check if we expect conversion issues
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment