Changing the documentation theme

Follow these steps to change the layout and functionality of the Antora documentation theme.

Prerequisites

To preview changes locally, the following prerequisites are necessary:

  1. Node environment

  2. Yarn installed

  3. Basic knowledge of how to use Antora

How-to steps

  1. Fork and clone this repository: https://github.com/ahus1/intellij-asciidoc-plugin.ahus1.de

  2. Fork and clone the plugin’s repository: https://github.com/asciidoctor/asciidoctor-intellij-plugin to a folder named asciidoctor-intellij-plugin as a sibling to the first repository.

    If the user chooses a different folder, they’ll need to adapt the folders in antora-playbook-author.yml.

  3. Change content for the theme in files antora-playbook.yml and antora-playbook-author.yml or sub-folder _antora

  4. Test the changes (recommended for every non-trivial change):

    1. Install all dependencies defined by the package.json file

      yarn install

    2. Set environment variables to enable search index creation

      set DOCSEARCH_ENABLED=true
set DOCSEARCH_ENGINE=lunr

    3. Build the static documentation website

      yarn author

    4. Start a minimal webserver to browse the documentation

      yarn serve

    5. Open documentation preview on http://127.0.0.1:5000/docs/

    6. Optional: To add the start page to the website, follow the steps in Changing content and layout of the start page, then run the following command:

      jekyll build --source startpage --destination _site

  5. Create a pull-request on GitHub

Once a maintainer approves the pull request your changes will be visible on the plugin’s homepage.