Project Structure and Configuration

This page describes the project structure and configuration in the docs-site and docs-ui folders.

docs-site

Important folders and files in the docs-site repository.

docs-site
|_ content
|_ lib
|_ ui
|_ antora-playbook.yml
|_ Makefile
|_ package.json
|_ package-lock.json

antora-playbook.yml

Antora’s default site generator is responsible for creating the documentation site from fetching to converting and arranging the content to publishing the files of the generated site. The site generator looks for the antora-playbook.yml file which tells how to run the site. It’s a simple configuration file written in YAML, JSON, or TOML. It has information like what content should be loaded, how site should be generated, where it should be published, configuring extensions for the project, specifying the UI bundle, so on.

You can specify the site configuration like landing page, site URL, title in this file. Then, you can specify the content source parameters like remote URL, start-paths. Content sources are the folders that has the actual content files written in AsciiDoc format. Antora looks for the content sources and loads the specified Git repositories or local content folders that has the files. To know more about setting up content sources, refer the next section about content folders. Antora also looks for the ui-bundle.zip file which is responsible for serving the UI of the website. Other information like Asciidoctor extensions must be specified in the playbook config file if you are using any third-party extensions that are compatible with AsciiDoc.

content

For HPC docs, the content folders follow a standard directory structure which are used to store the documentation component’s source files. Documentation component represents the page documentation for HPC and consists of a collection of files grouped into modules and share common metadata. There can be more than one documentation component for the site. Also, it follows a specific organization of files and directories which allow them to preset styles and behavior automatically.

content
|_ discovery
  |_ modules/ROOT
     |_ images
     |_ pages
     |_ partials
     |_ nav.adoc
  |_antora.yml
|_ index

Each folder contains atleast, component descriptor file(antora.yml), one module directory(ROOT), images directory, partials directory, Navigation file

antora.yml

Antora extracts the metadata defined in the file antora.yml and applies it to the documentation component. The following attributes need to be specified for the particular component in antora.yml file.

Attributes

Value

name

Component Name

title

Component Title

version

Version

display_version

Display version in the page

nav

path to nav.adoc file

The attributes name, title, version, display_version are straightforward and refer → nav.adoc for information about nav.adoc file.

modules directory

The modules directory consists of a discrete bundle of text, images, reusable components. You can have as many modules for the component depending on the documentation requirements. Inside each module, you can create folders like images, partials, pages, nav.adoc for the particular module. It’s recommended to create a ROOT module directory and Antora automatically applies component-level URLs to the page files in the ROOT module. This means that the pages in the ROOT module are promoted a level above other modules on the component’s URL. The images directory consists of the image files for the particular modules and pages contain the documentation written in AsciiDoc format.

Images directory

AsciiDoc supports png, jpg, svg, and gif files.

Example 1

images
|_ image-file.jpg

Example 2

images
|_new-folder
  |_ image-file.jpg

Pages directory

The documentation files are stored in the pages directory. These files are converted by HTML and publishes as individual pages in the generated site.

Example 1

page
|_ page-name.jpg

Example 2

pages
|_new-folder
  |_ page-name.jpg

You can create as many folders as you want under pages directory if you have more pages for the particular module..

Partials directory

Partials are reusable components that you can have across different pages/modules/components.

Example 1

partials
|_ partial-name.jpg

For more information about referencing pages, importing images, using partials, visit → Using Partials, Images and Referencing pages.

nav.adoc

This file contains the navigation routes for the particular module. It contains the reference links to pages in the modules and an example can be found below

* xref:index.adoc[Introduction]
** xref:getting-started.adoc[Getting Started]
** xref:Installation.adoc[Installation]
** Linux
*** xref:linux.adoc[Linux]

A new page created must be registered in the nav.adoc file to display in the website.

lib & ui folder

This directory is ideal for having external files/libraries while adding any extensions for the project. The ui folder contains the ui-bundle.zip file which is responsible for serving the UI for the website. This file can be generated by doing a build of your docs-ui repository. To see how to make a build, refer → How to build UI bundle?

Other Important Files

Makefile has several rules listed for the project build, preview site, install dependencies, so on. package.json lists the project dependencies, name, version, and other metadata.

docs-ui

Antora produces the website from the UI bundle created by doing a build of the docs-ui repository. It contains the UI assets like page templates, CSS, JavaScript, Images, etc and, Gulp build script. You can build it and preview the UI locally or you can fed it to the Antora site generator in docs-site to produce the website with UI integration.

The docs-ui is a fork of the Antora’s default UI → Antora Default UI and customized according to the project requirements.

Project Structure

Important folders and files in docs-ui.

docs-ui
|_preview-src
|_public
  |_src
    |_css
    |_helpers
    |_img
    |_layouts
    |_partials
|_gulpfile.js
|_package.json

public directory

Under public→src directory, list of files are available which are used to structure and style the documentation site pages generated by Antora. Some fo the file types are:

  • Handlebars(partials,layouts dir)

  • CSS

  • JavaScript(js dir)

  • Images(img dir)

Explanation

Handlebars is a template engine which can generate HTML files. Templates contain placeholders({{page.title}}) and the value can be passed and injected from a model. They’re present in the partials, layouts directories. partials directory contain templates which can be reused in several pages. For example, header, footer template can be reused in various pages. layouts directory consists of a template with {{> body}} placeholder. It’s an HTML page wrapper into which views can be rendered. The CSS files to add styles are placed under the CSS directory. JavaScript files are stored under the js & helpers directory.

Gulp

Antora uses gulp tool to automate tasks such as building/previewing UI, compiling files, generating UI bundle, so on. To build/preview changes, use the Makefile commands and execute it.

References

For more information about the Antora default UI, refer to → https://docs.antora.org/antora-ui-default/