Add Invisible HTML Element from SourceMaps
User Story: As a UI Developer, I need some markers in the statically generated Antora code referencing the source documents so that I can use that information in CR generation.
Background
Linking lines from a source document to lines of an output document is referred to as "creating a source map". This technique is used generally throughout different kinds of tranpilation, and Antora has a mechanism to do the same between lines of source AsciiDoc and output HTML.
There was a proof-of-concept effort done several years ago by a member that output elements into an AsciiDoctor output. It hasn't been shown that similar techniques could work with Antora, but the two tools are pretty intimately tied and the documentation suggests that it is possible.
See Antora Documentation on source maps.
Strategy
The basic idea here is to emit a <span>
, <div>
, or similar tag that doesn't cause any specific rendering in the output document, but gives future JavaScript something to operate on.
If possible, surrounding the entire output text in a <span>
would be ideal -- it lets code find the AsciiDoc source line by looking at the parent HTML element of any visible content.
It's likely that there will be complications for this -- advanced AsciiDoc usages like diagrams may not cleanly map appropriately to the source lines. If such cases are discovered, try to drop the mapping altogether. We're trying to solve the common case -- text regions.
Acceptance Criteria
- HTML output has tags indicating the AsciiDoc source line information that generated them.