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

feat(bici): generate BICI documentation (#17)

Integrate the BICI migrated content and document how this has been done for reuse with other content (based on previous poc).
The antora-ui bundle has been generated from a previous poc, it will be updated with content of bonitasoft/bonita-documentation-theme later

This also setup
    - build with npm: shared commands and shared dev/build setup
    - antora playbook: more ready for GH pages deployment
    - allow to build the site for local and production usage
    - allow to run local http server for evaluation
parent 4b872ae7
= New Bonita Documentation Site
// External URIs:
:url-antora: https://antora.org
:url-asciidoctor: https://asciidoctor.org/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation
*_DISCLAIMER: this is a work in progress._*
== Architecture
Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.
== Build
=== Requirements
{url-node}[Node 12.x] (may work with newer versions, no guarantee). For more details, see the https://docs.antora.org/antora/2.3/install-and-run-quickstart/[Antora installation guide].
While you can install Node from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to install and manage Node.
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.
NOTE: all npm commands are intended to be run from the repository root folder.
=== Build the static site for production
npm install
npm run build
The static site is then available in the `build/site` folder.
=== Local development
The `antora` CLI is available by calling `./node_modules/.bin/antora --version`
For more CLI options, see https://docs.antora.org/antora/2.3/cli/options/
==== Building for local developments
For a site that can be load from local disk
npm run local:build-static
For a site to be served by the development <<http server>>
npm run local:build
==== http server
Once the static site is build, you can run `npm run serve` and access to http://localhost:8080/ to check if everything is working correctly (urls in taxononmy, links, ....).
You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).
== Documentation
See the xref:./docs/README[dedicated folder].
=== Coming soon
\ No newline at end of file
title: Bonita documentation 2.0
url: http://localhost:8080/documentation
start_page: bonita::index.adoc
title: Bonita Documentation
# features that depend on the site URL: https://docs.antora.org/antora/2.3/playbook/site-url/#when-should-the-site-url-be-set
# when building for local usage, this is overridden.
url: https://bonitasoft.github.io/
start_page: bici::index.adoc
# see https://docs.antora.org/antora/2.3/playbook/configure-runtime/
cache_dir: ./.cache/antora
- url: https://github.com/alachambre/antora-sources-test.git
branches: [master, 7.11]
- url: git@github.com:alachambre/antora-source-api.git
- url: https://github.com/alachambre/antora-sources-test-2.git
# - url: https://github.com/alachambre/antora-sources-test.git
# branches: [master, 7.11]
# - url: git@github.com:alachambre/antora-source-api.git
# - url: https://github.com/alachambre/antora-sources-test-2.git
# local development: use ../bonita-ici-doc (see also https://docs.antora.org/antora/2.3/playbook/author-mode/)
- url: https://github.com/bonitasoft/bonita-ici-doc.git
branches: [master]
url: ../antora-ui/build/ui-bundle.zip
url: ./resources/antora-ui-bundle.zip
- ./lib/source-url-include-processor.js
\ No newline at end of file
= Migration tips: from markdown to asciidoctor
Note: current work used to migrate the BICI documentation, see https://github.com/bonitasoft/bonita-ici-doc/pull/118[PR #118]
== Markdown to Asciidoctor generation
=== Tool installation
TIP: Proposed tool Kramdoc aka https://github.com/asciidoctor/kramdown-asciidoc:[kramdown-asciidoc]. See also this https://matthewsetter.com/technical-documentation/asciidoc/convert-markdown-to-asciidoc-with-kramdoc/:[article].
* Require Ruby
* gem install kramdown-asciidoc, see the https://kramdown.gettalong.org/installation.html:[installation guide] for more details
* installation check: `kramdoc --version`
*TODO*: docker ruby image with gem installed to avoid polluting our machines?
=== Migrate sources
Sources (markdown and images files) are stored in the `md` folder of the documentation content repository.
index and releases-notes pages generally contain html elements that cannot be automatically migrated. +
There is also a dependency on font-awesome css (`fa-` directives). Font awesome support is available in asciidoctor
* 1st comment the html part
* Run the migration
* In the migrated content, manually migrate the html
Run the following command to generate the converted files:
find ./ -name "*.md" \
-type f | xargs -I @@ \
bash -c 'kramdoc \
--format=GFM \
--output=@@.adoc @@';
WARNING: test with additional `--wrap=ventilate` option
== Cleanup
Migrate custom Bonita tags for notes, warnings, ....
For instance, `:::info Note: for Enterprise, Performance and Efficiency editions only.:::` to
`NOTE: Note: for Enterprise, Performance and Efficiency editions only.`
sed -i 's/::: info/NOTE:/g' *.adoc
sed -i 's/:::info/NOTE:/g' *.adoc
sed -i 's/::: warning/WARNING:/g' *.adoc
sed -i 's/:::warning/WARNING:/g' *.adoc
sed -i 's/::://g' *.adoc
NOTE: for macOS add `''` after the -i option.
== rename files
for f in *.md.adoc; do mv -- "$f" "${f%.md.adoc}.adoc"; done
# Remove remaining md files
rm -rf *.md
== move file to the right folder
* Antora layout: move the `md` folder to `modules/ROOT/pages`
* taxonomy: move the page to `modules/ROOT/pages`, otherwise it is considered as a regular pages
* others
== images management
CAUTION: in progress, a definitive solution must be found
Antora expects (at least by default) that images are stored in the `modules/ROOT/assets/images` folder, then they are available
directly in pages as link without having to add relative path. In the generated site, they are then stored in the `_/_images` folder.
In the original markdown content, the images are accessed through the `images` relative folder. So, if the page content
is not changed, the images must be stored in
rm -rf build
antora --fetch antora-playbook.yml --stacktrace
This diff is collapsed.
"name": "bonita-documentation-site",
"version": "0.0.1",
"scripts": {
"clean": "rimraf build .cache",
"build": "antora --stacktrace --fetch --clean bonitasoft.github.io.yml",
"local:build-static": "antora --stacktrace --fetch --html-url-extension-style default bonitasoft.github.io.yml",
"local:build": "antora --stacktrace --fetch --url http://localhost:8080 bonitasoft.github.io.yml",
"serve": "http-server build/site -c-1 --port 8080"
"devDependencies": {
"@antora/cli": "^2.3.4",
"@antora/site-generator-default": "^2.3.4",
"http-server": "^0.12.3",
"rimraf": "^3.0.2"
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