同步操作将从 openGauss/debezium 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
The Debezium documentation in documentation is built using the Antora Framework.
The Antora framework is opinionated about its directory structure, which is why the folder layout is as follows:
documentation
| antora.yml
|
└─── modules
|
└─── ROOT
| nav.adoc
|
└─── pages
|
└─── (content)
The Antora documentation system uses a concept called component descriptors. Debezium makes use of a single component descriptor called ROOT
since we want to document all features in a single section. In the future if we find documenting connectors or certain features separately from others, we can look at using multiple component descriptor layouts, however for now we use the ROOT
descriptor for this purpose.
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.
In the Antora-based documentation, there are two styles of links, External and Internal.
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:<scheme>://<host>/<path-to-resource>(<text-friendly-name>)
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:<version>@<component>:<module>:<path-to-file><#fragment>[<text-friendly-name>]
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.
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.
A component descriptor is identified by the existence of an antora.yml
file located in the root of the component's documentation layout. The most important aspect of this file pertains to the version
attribute found in the file's contents:
name: debezium
title: Debezium Documentation
version: `0.10`
nav:
- modules/ROOT/nav.adoc
The name
attribute describes a path that will be appended to the Antora's base build path. This allows differing components to output their documentation content separately.
The title
attribute describes a UI friendly name for this component. Since Debezium uses a single ROOT component, all documentation will be located under the name Debezium Documentation
in the UI.
The nav
attribute describes an array of navigation AsciiDoc files uses to build the left navigation pane. Debezium makes use of a single navigation file.
The version
attribute is the most important aspect of this file. This designates the naming convention to be used when referencing what version this documentation represents. This can be an actual version number as shown above, in which case it should be quoted. Other examples could be things like stable
or latest
.
NOTE: As of Antora 2.3, the antora.yml
file can now define Asciidoc attributes, which are discussed below.
Should a documentation page need to reference attributes, e.g. version numbers, this can be accomplished in two ways:
antora.yml
component descriptor in this repository.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,
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.
The current antora.yml
component descriptor looks similar to the following:
asciidoc:
attributes:
debezium-version: '1.1.0.Final'
debezium-dev-version: '1.2'
debezium-kafka-version: '2.4.0'
debezium-docker-label: '1.1'
install-version: '1.1'
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'
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.
The playbook files in the website repository use the same layout, shown here:
# Global asciidoc attributes here, used across all versions of documentation
asciidoc:
attributes:
prodname: 'Debezium'
context: 'debezium'
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.
Follow these guidelines for contributing to the Debezium documentation.
AsciiDoc attributes are effectively like variables, enabling you to insert short snippets of text into the documentation.
They are typically used for abstracting content like version numbers, branding, and root URLs.
For example, to insert the contents of the prodname
attribute (which currently resolves to Debezium
), use the AsciiDoc syntax, {prodname}
.
We recommend that you use the following attributes when contributing content to the Debezium documentation:
{prodname}
instead of Debezium.See the Attributes section for more details.
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.
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[]
Note the following advantages of the xref:
macro:
custom-connector
ID is defined.
AsciiDoc automatically figures this out at build time.To add an image to the documentation:
documentation/modules/ROOT/assets/images
directory.image::MY_IMAGE.png[]
(or for an inline image, image:MY_IMAGE.png[]
).At build time, AsciiDoc reads the value of the standard imagesdir
attribute to discover the location of images.
There is no need to set this attribute yourself, it is already defined for you.
Note that if you view or render a single AsciiDoc file, you will not be able to view the image.
Because of the way the images are organized (in combination with the imagesdir
attribute), you can only see the images correctly rendered when you build the whole documentation set using Antora.
Note the following additional recommendations:
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。