Changing the Section Action Menu to a Block Action Menu
This modifies the section action menu to operate at the AsciiDoc Block level, rather than only at the section level. This relies on the antora-include-source-location plugin to generate the source location data elements.
Testing
This adds in a new Antora testing site, which has three different document components:
- Specific UI Test Pages created by our team to test various combinations of Antora/AsciiDoc syntax in a compact way
- The Open Group Standards Template, from the publicly accessible source
- The AsciiDoc Language Syntax documentation, from the Eclipse Foundation
This is accessible in any pipeline of this Antora project.
Test Site for the Latest Pipeline on block-action-menu
Principles
Anchored Blocks
Some AsciiDoc blocks have an ID attribute, which I refer to as "Anchored Blocks". This means that you can directly link to them by adding the ID as the document fragment of the URL (the part after the #
character). It also means you can create a link to it from within the document, using the Antora xref::
macro.
Blocks that are anchored will have menu options for copying the HTML link and the Antora XRef. Blocks that are not anchored will not have these options present, though they may still have other options (like submitting a CR).
Titled Blocks
Some blocks have titles on them. The most common way is to have a line beginning with a dot just prior to the block, such as
.Title of Block
Block text
If the block is titled, the CR template will identify the block using the title. If it is not titled, it will have a generic "Type + Count", such as "Paragraph 2".
Breadcrumbs
Each block has a breadcrumb trail, which starts at the Page level and refines down by containers (such as sections). The CR Template outputs the entire breadcrumb table, so that you can find block in question easier. For example:
Antora Location | |
---|---|
Page | Article Name |
Section | Section Title |
Paragraph | 2 |
Without these breadcrumbs, identifying paragraphs by their overall count (like "Paragraph 54") would be unfriendly to humans trying to locate the relevant section. Each of the breadcrumb entries will have a link to their corresponding Antora output location IFF that is available. For items without an anchor, the text is displayed without a corresponding link.
If there are no "Page" entries (pages that don't have an H1 header), one is inserted using the AsciiDoc filename (without extension).
Known Bugs
These bugs are considered small enough to be fixed in later iterations, rather than trying to perfect the design here.
- Floating Images have source mapping information, but it was difficult to create the UI menuing around them. They have been suppressed, so they render without the ability to take actions on them.
- Some blocks, like Example Blocks or Admonitions, can have subblocks (like Paragraphs). The menu selector for these inner blocks visually overlaps the selector for the outer element.
- Collapsible Blocks Menu Bars are too far to the right, and overlap with the main content.