Most importantly, note that https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[every sentence should be on its own line].
[[snippets]]
== Fedora Documentation snippets
When you write Fedora Documentation, some things come up frequently.
You can create a redirect from an old page to a new one by using the https://docs.antora.org/antora/latest/page/page-aliases/[`page-aliases`] attribute.
The syntax is the same as for xref:#internal-link[xref links].
.Example 1. In new-page.adoc
[,adoc]
----
= Page Title
:page-aliases: old-page.adoc
----
You can also create a redirect from another module or component.
You can add syntax highlighting to any source block by setting the source language attribute.
.Example of setting the source language attribute to a code block
------
[,yaml]
----
output:
clean: true
dir: ./public
destinations:
- provider: archive
----
------
.Example of rendered code block with such attribute
[,yaml]
----
output:
clean: true
dir: ./public
destinations:
- provider: archive
----
The list of supported languages can be found in the https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/blob/main/src/js/vendor/highlight.bundle.js[highlight.bundle.js in the Fedora Docs UI].
=== Datatables
You can convert a regular table to a https://datatables.net/[DataTables] using the `datatable` role attribute.
DataTables provides filtering and ordering capabilities.
.Example of defining a DataTable
[,asciidoc]
----
[.datatable]
|===
|colA | colB | colC | colD
| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===
----
.Rendered DataTable
[.datatable]
|===
|colA | colB | colC | colD
| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===
Additional roles can be used to add DataTables features:
- `dt-search`: add search box
- `dt-paging`: add pagination
You can also alter the styling with the help of https://datatables.net/manual/styling/classes[built-in DataTables classes], such as `display` or `compact`.
.Example of using additional options
[,asciidoc]
----
[.datatable.dt-search.display]
|===
|colA | colB | colC | colD
| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
|===
----
DataTables real usage can be seen on the xref:legal::not-allowed-licenses.adoc[Legal documentation].
A table of content is automatically generated on the right of each pages.
IMPORTANT: There is no need to add the `:toc:` attribute as it will then add a duplicate table of content to the document.
The right-sided table of content only displays title levels up to level 2 by default.
You can change this setting with the `page-toclevels` attribute.
[,asciidoc]
----
= Page Title
:page-toclevels: 3
----
=== Pagination
If you have several pages that follow the same topic, you might be interested in enabling the pagination. +
Pagination allows the reader to easily navigate to next and previous pages from the navigation tree by adding navigation links at the bottom of the page.
This option is enabled by the `page-pagination` attribute.
To keep consistency in presenting a button, keyboard bindings, or a menu item (path), Button and Menu UI Macros communicate to the reader what actions they need to take.
IMPORTANT: Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc and used in latest Quick Docs edited.
This option is enabled by the experimental attribute.
[,asciidoc]
----
= Page Title
:experimental:
----
Examples of defining Button UI Macro
[,asciidoc]
----
. Click btn:[Create].
. Choose a passphrase that is strong but also easy to remember in the dialog that is displayed.
. Click btn:[OK] and the key is created.
----
Examples of defining Menu UI Macro
[,asciidoc]
----
To save the file, select menu:File[Save].
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
Optionally, you can add https://docs.asciidoctor.org/asciidoc/latest/document/author-line/[authors] and https://docs.asciidoctor.org/asciidoc/latest/document/revision-line/[review] metadata.
.Example 1 - Authors and revision information
[,asciidoc]
----
= Page Title
Ben Cotton; Peter Boy; Petr Bokoc
2.0, 2022-11-26: fix for F37
----
You can decide to omit the version number, if you don't need that information.
.Example 2 - Revision information without version
[,asciidoc]
----
= Page Title
Francois Andrieu
2022-12-10: Added revision metadata example
----
While these metadata are optional, try to keep at least the revision date so readers know how up-to-date the page is.
