[go: up one dir, main page]

Use keepSource setting on global AsciiDoc config instead of proxying page.src to preserve src.contents property

Normally, the AsciiDoc source of a page (a virtual file in the content catalog) is replaced with the generated HTML when Antora converts the page (i.e., the contents property value is changed from AsciiDoc to HTML). However, Assembler requires access to the AsciiDoc source for a page in order to construct the aggregate document to convert.

Currently, Antora eagerly assigns the initial value of the contents property to the src.contents property, then proxies the src property to prevent the src.contents property from being deleted. While this works, it's not elegant and may introduce a conflict with other extensions.

Antora provides a built-in way to preserve the AsciiDoc source on the page. If the keepSource property is set on the global AsciiDoc config, Antora will ensure that src.contents is set to the original value of the contents property (the AsciiDoc source) and will not delete this assigned property. Assembler should make use of this functionality.

In doing so, it will bump the minimum required version of Antora to 3.0.0, which just needs to be documented.

If the src.contents property is not set on a page, Assembler should skip it and log a warning. This will prevent Antora from crashing if another extension adds a page that is missing this property.