diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 8a67f98d6..524fbc78b 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -32,7 +32,7 @@ The Antora framework is opinionated about its directory structure, which is why | └─── pages | - └─── (content) + └─── (content) ``` ### Component descriptors @@ -43,28 +43,6 @@ The Antora documentation system uses a concept called component descriptors. De All documentation content should be added under the `pages` directory and should use the extension `.adoc` for consistency. The hierarchy used for pages under this point is mainly for organizational purposes for documentation writers. If you wish to reference a specific `.adoc` from another file, the directory hierarchy will be used in the cross reference link however. -### Linking to content - -In the Antora-based documentation, there are two styles of links, _External_ and _Internal_. - -#### External - -An external link is one that points to a resource that is not maintained in the Antora documentation. In order to link to these resources, you should use the normal AsciiDoc `link` macro as shown below: - -``` -link::///() -``` - -#### Internal - -An internal link is one that points to a resource _in_ the Antora documentation. Antora comes with a special AsciiDoc macro called `xref` that should be used for this purpose. This macro should be used as shown below: - -``` -xref:@::<#fragment>[] -``` - -As an example, if you want to link to a file called `example.adoc` within the same component and for the same version of the documentation being rendered, you would write the link as `xref:example.adoc[This is my example]`. More information on Antora's page-id structure and how to build links can be found [here](https://docs.antora.org/antora/2.1/page/page-id/#how-is-a-page-referenced-with-its-id). - ### Navigation Pane The Antora documentation layout uses a navigational pane on the left-side of the UI. This navigation pane is driven by content found in the `nav.adoc` located inside the component descriptor's top-level directory. This file must be **manually** maintained when a new topic is to be present in the left navigation layout. You can see our current navigation pane layout [here](https://wwww.github.com/debezium/tree/main/documentation/modules/ROOT/nav.adoc). @@ -100,10 +78,10 @@ Should a documentation page need to reference attributes, e.g. version numbers, The general rule is if an attribute changes frequently or is related to a specific version or subset of versions of Debezium, it likely belongs in the `antora.yml` file in this repository. If the attribute changes infrequent or is not specific to a given version of Debezium, its easier to maintain that in the various playbook files in the Debezium website repository. -Lets say we need to add an attribute that points to our JIRA issue for issue links, +Lets say we need to add an attribute that points to our JIRA issue for issue links, that would be an example of an attrbute that would be defined in the playbook. -But if we needed to add an attribute that points to a specific version of a Maven artifact or reference a specific version of a dependency, -that's more appropriate for the `antora.yml` component descriptor located in this repository. +But if we needed to add an attribute that points to a specific version of a Maven artifact or reference a specific version of a dependency, +that's more appropriate for the `antora.yml` component descriptor located in this repository. The current `antora.yml` component descriptor looks similar to the following: ``` @@ -117,11 +95,11 @@ asciidoc: assemblies: '../assemblies' modules: '../../modules' mysql-connector-plugin-download: 'https://repo1.maven.org/maven2/io/debezium/debezium-connector-mysql/1.1.0.Final/debezium-connector-mysql-1.1.0.Final-plugin.tar.gz' - mysql-version: '8.0' + mysql-version: '8.0' strimzi-version: '0.13.0' ``` -Attributes are defined by creating a nested yaml structure under `asciidoc.attributes` where the key-value attribute pairs are to be defined. +Attributes are defined by creating a nested yaml structure under `asciidoc.attributes` where the key-value attribute pairs are to be defined. The playbook files in the website repository use the same layout, shown here: ``` @@ -133,7 +111,7 @@ asciidoc: jira-url: 'https://issues.redhat.com' # because of how handlebars templates work with page.attributes, this must be prefixed with "page-" page-copyright-year: '2020' -``` +``` **NOTE**: Given that the Debezium documentation is consumed downstream by other processes, do not define attributes in the `_attributes.adoc` file and use it as an include nor should you define attributes locally in a given .adoc file. @@ -153,27 +131,72 @@ We recommend that you use the following attributes when contributing content to See the [Attributes](#attributes) section for more details. -### Cross references +### Adding cross-references that link to other content -If you need to link to another section or location anywhere in the Debezium documentation, the recommended approach is to use anchor IDs in combination with the `xref:` cross-referencing macro. +The Debezium Antora-based documentation uses two styles of links for creating cross-references to other content, _External_ and _Internal_. + +#### External links + +An external link is one that points to a resource that is not included within one of the Debezium AsciiDoc files. +To link to an external resource, use the AsciiDoc `link` macro as in the following example: + +``` +link::///[] +``` + +For example: + +``` +link:https://docs.antora.org/antora/latest/navigation/xrefs-and-link-text/[Antora linking documentation] +``` + +#### Internal links + +An internal link is one that points to a resource that is included in one of the Debezium AsciiDoc files. +The target of an internal link is the anchor ID that is defined for the element that you want to link to. +For example, to link to a section header with the name _Custom connector_, the header must have an anchor ID defined on the line that precedes it, as in the following examples: -For example, if you want to link to a section called _Custom connector_, first of all define an anchor on the line preceding the heading, as follows: ``` [id="custom-connector"] == Custom connector ``` -You can then link to this section from anywhere in the documentation using this syntax: ``` -xref:custom-connector[] +[[schema-change-topic]} +== Schema change topic ``` -Note the following advantages of the `xref:` macro: -* You do not need to specify or know the location of the file where the `custom-connector` ID is defined. -AsciiDoc automatically figures this out at build time. -* Consequently, if you move files around, you will not break any links. -* When you build the documentation, AsciiDoc automatically converts the cross-reference into a link using the title text, _Custom connector_, in the link. -If you change the title of the section, AsciiDoc will automatically update the link text to match. +The method that you use to construct the link depends on whether the link targets content that is in the same AsciiDoc file or in a different file. + +##### Links that target content within the same file +To link to content within the same file, use the AsciiDoc `xref` macro. +To use the `xref` macro, construct the link as in the following example: + +``` +xref:[] +``` +For example, +``` +xref:custom-connector[Custom connector] +``` +Although the Antora framework that we use to publish the Debezium documentation can accept an empty `[]` value, to enable the Debezium documentation to be consumed downstream in other frameworks, it's necessary to supply a `[]` value. + +##### Links that target content in a different file +To link to Debezium content that is in a different file, construct the link according to the following format: + +``` +{link-prefix}:# +``` +For example, + +``` +{link-prefix}:{link-outbox-event-router}#basic-outbox-configuration +``` +In the Antora-based documentation, the `{link-prefix}` attribute resolves to the `xref` macro, but when the content is reused downstream, it can contain a different value. + +Similarly, in the Antora-based documentation, the `` corresponds to the path to the targeted file, but when the content is rendered in a downstream framework, it can contain a different value. To determine which category attribute to use when linking to a different file, see the `link-*` attributes that are listed in the `asciidoc` section of the [`documentation/antora.yml`](../documentation/antora.yml) file. + +Although the preceding format is not required for the Antora-based documentation, it is required to enable the Debezium documentation to be consumed in other downstream frameworks. ### Adding images