Add a per-component antora author mode
Author mode is good.
However, it can be useful to be able to use author mode against a single component, during development, without a dedicated (possibly multi-component) external site-workspace.yml
playbook.
Specification
If the -a | --auto-author
flag is specified to generate, the argument is not the playbook, but an antora.yml
component file.
If that is done, antora uses a default site.yml
file, which is as follows:
site:
title: {{ title }}
url: https://127.0.0.1
start_page: {{ start_page }}
content:
sources:
- url: ./
branches: HEAD
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true
output:
clean: true
Where {{ something }}
refers to keys in the antora.yml
component file.
It shouldn't be needed to specify start_path
for the component, because it will be possible to run antora
in the subdirectory where antora.yml
is.
Alternatively, it can be autodetected based on the path given to the antora.yml
file.
Implementation Details / Potential Difficulties
When antora's generate
command is detected, but the -a
flag has been used, antora will:
- Verify that the argument path is valid (will be detectable by the default author mode playbook)
- Parse the file
- Generate the site.yml playbook using the found data
- Instantiate the generator with the resulting playbook
- it must be possible to pass a string (rather than a file path) to the generator
- it must be possible to parse the component
antora.yml
(and other formats) files before the generator is initialized
In the scenario that passing strings ends up being too complex (though the upcoming 2.0 release is allowed to break compatibility), it is also possible to generate the site.yml
playbook as a file, in the cache directory.