Architect the document converter component
Define the architecture for the document converter component. When we say page here, we're referring to the top-level AsciiDoc documents that become the documentation (article) pages. This component is responsible for handling the conversion from AsciiDoc to HTML. That HTML is then used to replace the contents
property on the vinyl (virtual) file. (The assigned HTML may get enclosed in a template to make it a standalone page in a subsequent step in the pipeline).
At a high level, this component is just a transformer that acts on the files in the "pages" family in the file catalog.
This component actually performs two functions: read and convert.
In the read step, the component should do the following:
- parse the AsciiDoc content into an AST by calling
Asciidoctor#load
- pass any options and attributes to
Asciidoctor#load
that are required for the document to work with Antora (see below) - pass custom attributes defined by the user in the playbook
- pass any options and attributes to
- assign the AST to a property on the file
- name the property
ast
orasciidoc.ast
- name the property
- supply a custom include processor that resolves includes from within the (virtual) file catalog
- the include processor should be an exportable function so it can be tested and reused
- if an include cannot be resolved, the generator should log a warning (meaning, don't be silent)
- supply a custom xref processor that resolves inter-page xrefs (which will be called during conversion)
- assign attributes from the header to a property on vinyl (virtual) file
- name the property
attributes
orasciidoc.attributes
- name the property
In the convert step, the component should do the following:
- call convert on the AST
- assign the converted result to the
contents
property on the file - set the extname on the file to file.out.extname (no need to hardcode
'.html'
here) - remove the AST from the virtual file so it can be garbage collected eagerly
Here's a list of the options that should be set when calling Asciidoctor#load
:
- safe = 'safe'
Here's a list of mandatory attributes that should be set when calling Asciidoctor#load
, which cannot be overridden:
- docname = file.stem
- docfile = file.path
- docfilesuffix = file.extname
- env-site = ''
- imagesdir = file.out.moduleRootPath + '/_images'
- attachmentsdir = file.out.moduleRootPath + '/_attachments'
- samplesdir = file.src.moduleRootPath + '/samples'
- fragmentsdir = file.src.moduleRootPath + '/content/_fragments'
Here's a list of default attributes that should be passed to Asciidoctor#load
, but should be allowed to be overridden if defined in the playbook:
- source-highlighter = 'highlight.js'
- sectanchors = ''
- idprefix = ''
- idseparator = '-'
- icons = 'font'
Acceptance criteria:
-
Define behavior of document converter component -
Define API methods, inputs, and outputs -
Decide the name of the package -
Define the state, if any, the component maintains