search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
80 stars 67 forks source link

add functional xrefs to templates #171

Closed ryandeussing closed 5 months ago

ryandeussing commented 2 years ago

113 establishes that xrefs can be used in modules. the template files were updated with this information, but they do not include functioning xref examples.

  • A bulleted list of links to other closely-related material. These links can include link: and xref: macros.

I'm working with a writer who is unable to get an xref within a module to validate, and the advice I'd like to give is "see how that's done in the template".

mjahoda commented 1 year ago

I believe that the templates should not serve as tutorials of something what is not mod-docs-specific. Hope that I am not missing the point but for the use case you described, I would refer to: https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references (for example)

emmurphy1 commented 1 year ago

The reason we have held off from providing a specific example of an xref is that we have been waiting for the new publishing platform for years. With Pantheon II and then Jupiter, it looked like we would be able to use cross-references that linked outside of an assembly. Now, we are waiting to see what possibilities or limitations WFM will offer or impose. In the meantime, this is the syntax that I use: xref:con-vrp_{context}[]

In this example, con-vrp_{context} is the anchor ID of a module that is included in the assembly that contains the xref. Include empty brackets at the end ([]) to substitute the title of the module. Include the {context} variable in case the assembly is nested. If you omit the {context} variable and the assembly is nest, the xref will fail. It will also fail if you do not define the context variable in the assembly file.

mjahoda commented 5 months ago

On today's modular documentation steering committee meeting, we agreed on closing this issue as something we do not want to address in the templates. We believe that basic usage of cross-references is covered by the AsciiDoctor manual [1], it might be defined company-wide (for example, [2]) or specified on the project-level (for example, [3]).

[1] https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references

[2] https://redhat-documentation.github.io/supplementary-style-guide/#links

[3] https://gitlab.cee.redhat.com/red-hat-enterprise-linux-documentation/rhel-8-docs/-/wikis/Creating-safe-(conditional)-xrefs