search

asam-ev / asam-project-guide

(WIP!) Project Guide for ASAM OpenX standards
Mozilla Public License 2.0
2 stars 0 forks source link

Embedding of source elements (xml schema, ...) with display and download #138

Closed philipwindecker closed 2 years ago

philipwindecker commented 2 years ago

Create a showcase on how source code can be easily both displayed inside an Antora page and have a download button / link.

philipwindecker commented 2 years ago

Antora provides the Attachment folder concept specifically for this purpose: Content in the attachment folder is hosted as literal files and can be downloaded (see https://docs.antora.org/antora/latest/page/attachments/). Meanwhile, the same files can also be included with the include macro and, thereby, displayed within an Antora page.

If content is to be displayed partially, add tags to the source content using standard comment structure. See https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/

Besides the simple download link in the page's body (using the xref macro), a button can be added in the UI. However, this is by default more manual setup. To automate this, a script could be conceived to generate the required html code from the antora content. However, this would require some requirement engineering first to ensure that topics like order, labeling, positioning, etc. are well defined first.

philipwindecker commented 2 years ago

The examples are included as a separate component in the same branch/MR as in #133 . See https://github.com/asam-ev/asam-project-guide/issues/133#issuecomment-1116163604