QENTA Online Guides
Overall Structure
Organized as Git Submodules
UI Customizations, Layout, Styles, frontend JS, search: ui-customizations/
Content, pages, navigation, antora.yml: content/
Recommended Workflow
Folders content
and ui-customizations
are submodules of qenta-docs-content
and qenta-docs-ui-customizations
.
1. Clone Recursively
2. Make Changes
After changing content, UI or any other part inside the submodules directories, push the changes to the submodule(s) first.
Then push current repo to trigger a build.
Pushes to master
branch will be deployed publically to gh-pages
Pushes to any other branch shall be deployed to S3/branches/branch_name/
Build and Dev Locally
Highly recommended to use the Dockerfiles (ui and antora) via the Makefile for each step.
Update UI
qenta-docs-main
rebase/merge from https://gitlab.com/antora/antora-ui-default.git
qenta-docs-ui-customizations
rebase/merge from https://github.com/Mogztter/antora-lunr.git
1. Build the UI
make ui.build
This creates build/ui-bundle.zip
containing the UI, see it referenced in antora-playbook.yml
Pay attention to output, linter is very strict and will not build the UI if you're sloppy.
2. Build the Documentation
make antora.build
Creates the web pages in build/site/
3. Start Local Webserver
Contained in antora.dockerfile
make antora.run
NOTE: Console output says port 8080
but this is inside Docker, the forwarded port on localhost
is 8051
, see docker-compose.yml
Important Files
Global Control
antora-playbook.yml
Disable displaying a Page Edit button
url
can be a repository url or local folder. In our case it is both: a Git submodule
content:
edit_url: ~
sources:
- url: ./
branches: HEAD
start_paths:
- content/*
Content Control
antora.yml
Page Navigation
Navigation on the left of the page is controlled by content/online-guides/modules/ROOT/nav.adoc
It is a simple list of pages and their hierarchy.
Dockerfiles
To add search functionality antora-site-generator-lunr
is installed in the container.
See antora.dockerfile
for required ENV variables if you run antora without the provided Dockerfile/Makefile commands.