[go: up one dir, main page]

Skip to content

Use location of antora.yml as ROOT module location if modules/ROOT is absent

In the spirit of convention over configuration (in contrast with #28), and to make the Antora structure easier to understand for cases when modules are not needed (most often for newcomers), it should be possible to put the contents of the ROOT module adjacent to the antora.yml file instead of nested in the modules/ROOT directory. We consider this an improvement since the concept of a ROOT directory may be unfamiliar to those who don't have a background in web servers. They can thus avoid using the directory altogether.

Using this convention, the following structure:

antora.yml
modules/
  ROOT/
    pages/
      index.adoc

can be reduced to:

antora.yml
pages/
  index.adoc  

This location for the ROOT module is only considered if the modules/ROOT directory is absent.

If non-ROOT modules are introduced, they can still live in their normal location:

antora.yml
pages/
  index.adoc
modules/
  name-of-module/
    pages/
      index.adoc

An open question that remains is whether the modules/ROOT directory should prevent the use of the implicit ROOT module directory per component version or per origin (i.e., instance of antora.yml). I think the ideal scenario is to correlate it with an origin since pulling in an additional content source for a distributed component could inadvertently cause this feature to stop working, which would be confusing. There would be no such risk if the search is done per origin since the relevant directories are in the same file system as the antora.yml file.

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information