modifié le

Various components

Site

An Antora site is :

  • metadata describing the site (a YAML playbook),

  • a set of components, which constitute the documentary background of the site,

  • a look (UI), implementing rendering.

Antora strictly separates content from rendering.

All components of a site take on the look defined by the UI associated with this site. A component integrated into different sites will therefore take on the look of their site for each of them. (in other words, there is no notion of rendering in a component).

In this demo, the site is all the course materials provided by the author to a given promotion (promotion=sector+year). If the author intervenes in several promotions (for example in licence informatique, licence pro développement web et master datascience), then each of them will have its own site.

The UI used is Antora Default UI.

There is no navigation system managed at a site level.

The home page of this demo site is a referral to the components of this site. This AsciiDoctor page was made by hand, as a simple list of links:

= Master Data Science

Index des supports de cours (factices) du master Data Science::

* xref:C:ROOT:index.adoc[Programmation C]
* xref:apache:ROOT:index.adoc[Apache]
* xref:genie_logiciel::index.adoc[]
* xref:python_objet:ROOT:index.adoc[]

Le making of::

* xref:makingof:ROOT:index.adoc[Supports de cours avec Antora]
* xref:En@makingof:ROOT:index.adoc[Course materials with Antora]

Component

A component is a treated subject (here, a course material). Concretely, it is a git repository containing interconnected and self-sufficient documents. It is defined by a playbook named antora.yml.

Although the components of a site are independent of each other, links from one may nevertheless refer to pages from another.
Example 1. genie_logiciel/antora.yml

The antora.yml playbook of the genie_logiciel component is:

name: genie_logiciel
title: Génie logiciel
version: 2022
start_page: ROOT:index.adoc
nav:
- nav.adoc

A component is self-sufficient. As a git repository, it has its own history, successive versions, etc.

For the student, a component is identifiable in the URL, whose form is "site/component/version/…​".

The components of this demo site are master, C, apache, genie_logiciel, python_objet et making_of, labeled respectively as Master Data Science, Programmation en C, Serveur Apache, Génie logiciel et Python Objet and Making Of..

A component has its own navigation.

In the demo site, the navigation of the genie_logiciel component is a nav.adoc file containing a multilevel list:

* xref::intro.adoc[]
* xref::processus.adoc[Processus de développement]
* xref::fortran.adoc[]
* xref::python.adoc[]

* Problème
** xref:probleme:sujet.adoc[Sujet]
** xref:probleme:solution.adoc[Solution]

A site can assemble several versions of the same component. Playing cleverly with git, you can couple different versions of a component to the branch of the corresponding repository.

In the site, we notice different versions relating to the year (2020, 2021, 2022, default, Fr and En). These versions effectively correspond to git branches. But we will see later that these are not the only existing versions.

A component is structured in modules.

Module

A module is a set of logically linked files. There are *.adoc source files (pages directory), the images included in these pages (directory images), files intended to be downloaded from these pages, such as PDF documents, sample source codes, etc. (directory assets/attachments and examples), as well as portions of source pages (partials directory). Physically, a module is a subtree of component directories. Unlike a component which exists independent of the site that publishes it, a module does not have its own existence apart from the component to which it contributes. It’s just a way to organize the component.

For the student, a component is identifiable in the URL, whose shape is "site/component/version/module/…​".

You can define a navigation at the level of a module. So different strategies are possible:

  • manage the navigation of a component in a single file,

  • manage the navigation at the level of each module, and aggregate (with include) these navigation files at the component level,

  • mix the 2.