_site_README.adoc

Building this site with Jekyll

We’re assuming ruby, gem and bundler are already installed on one’s system.

bundle install
bundle exec jekyll build .
# or bundle exec jekyll serve .

The current theme is greatly based on the Jekyll Asciidoc Quickstart, which is itself based on the jekyll-asciidoc plug-in, required because we use Asciidoc for our documentation.

Caveats

Most normal features of Jekyll and CSS themes can be used, but a few things need to be considered, as it appeared:

1. Make sure that each README.adoc is soft-linked to an index.adoc. The first one is understood by GitHub as landing page for a directory (but only if it’s a regular file). The 2nd one is rendered as regular file by Jekyll, and understood as well as default page for a directory then.

2. CSS/HTML class can be assigned, e.g. to links in the navigation bar, using the role attribute.

3. Similarly the ID attribute can be assigned (we don’t use it explicitly yet).

4. Instead of using the usual front-matter format, Asciidoc prefers header variables prefixed with page-, e.g. :page-name: my-page-name.

5. The specifics required to integrate the documentation into Jekyll should nevertheless be kept to a minimum as to not cripple documentation writers, and make documentation still readable directly in GitHub.

To Be Done

Few things could still be addressed in due time:

1. code hightlighting doesn’t seem to work (didn’t try yet)

2. Font-based Admonition and Inline Icons don’t seem to work (tried, failed).

3. a clearer separation of user and developer documentation might be helpful, also physically in different sub-folders (to be reflected in pyproject.toml for packaging).

4. a more automated generation of the navigation bar could then possibly be addressed, with an overarching Table of Content accross the whole site.

5. the whole style could use a professional revamp, especially the footer looks uncool to my eyes.