Docs Site
Antora
Koble uses Antora for the documentation site as it uses Asciidoc which is simple to use yet has an extensive list of features.
If you are unfamiliar with Asciidoc, it is conceptually similar to markdown and is easy to use. The syntax reference is a useful resource for writing asciidocs.
The install guide for Antora can be found here.
Building The Site
The site can be built using please.
plz build //:site
# OR if you haven't installed plz
./pleasew build //:site
This will output the static files to plz-out/gen/site.
You can easily preview this with a static webserver. If you have Python3 installed you can run:
python3 -m http.server -d plz-out/gen/site
Then go to http://localhost:8000 to preview the site.
Github Pages
This is only relevant for project collaborators with direct access to the GitHub repo. |
A GitHub action is available through .github/workflows/publish.yml
,
which allows the contents of docs/build
in the main branch
to be pushed to the root of the gh-pages branch.
This is hosted as a static site with Github Pages.
First build the site and copy to docs/build:
plz build //:site
cp -r plz-out/gen/site docs/build
Once this has been pushed to the main
branch on GitHub,
you can go to the
publish action
page and press Run workflow, making sure the main
branch is selected
then pressing to confirm.