Estilo AsciiDoc

Equipo de Documentación Fedora <https://discussion.fedoraproject.org/tag/docs> v1.0, 10/12/2022

Esta página comparte información general sobre escritura en AsciiDoc así como sintaxis específica de Fedora/Antora que viene a menudo en la Documentación de Fedora.

Básico para AsciiDoc

AsciiDoc es un lenguaje de marcador ligero para autoría de notas, artículos , documentación, libros, páginas web, presentaciones de diapositivas y páginas man en texto plano.

— asciidoctor.org

Referencia Rápida de Sintaxis AsciiDoc: Handy cheat sheet of what the AsciiDoc markup looks like. Use this for quick references and checking up on how to formatting, lists, media content (images and video), table of contents, and more.
AsciiDoc Recommended Practices: Best practices about writing in AsciiDoc. Most importantly, note that every sentence should be on its own line.

Fedora Documentation snippets

When you write Fedora Documentation, some things come up frequently. They may not be documented in general AsciiDoc documentation, like on asciidoctor.org. + This section contains handy references for Fedora Documentation writers to copy and paste in their own AsciiDoc documents.

Internal links

In this section, we will use the following repository structure as an example:

Example of documentation repository structure

📄 antora.yml (1)
📂 módulos
  📂 RAÍZ
    📂 páginas
      📄 index.adoc
      📄 otra-página.adoc
      📂 sub-dir
        📄 reglas.adoc
  📂 council
    📂 páginas
      📄 guia-normativa.adoc

1	Defines the documentation component as test-module (attribute `name`)

Same repository

Use the local path relative to the pages directory in the same module.

Link to a page at the root level

xref:another-page.adoc

Link to a page in a subdirectory of pages

xref:sub-dir/rules.adoc

El mismo repositorio, módulo diferente

Like an internal link, but use a colon (:) to separate the module name. If you are not sure if you need this, you likely don’t! Multiple modules bundled in the same repository is not currently a common scenario in Fedora Documentation.

Ejemplo 1

xref:council:guiding-policy.adoc

Repositorio diferente

Enlazar a otra página de Documentación Fedora que exista en otro repositorio. Note que debe utilizar el campo nombre especificado en el archivo antora.yml en el otro repositorio o no funcionará. En caso que el nombre del módulo destino es RAÍZ, puede omitir el nombre pero aún necesita el dos puntos adicional (:).

Ejemplo 1, ambos enlaces son equivalentes

xref:test-module::another-page.adoc
xref:test-module:ROOT:another-page.adoc

Ejemplo 2

xref:test-module:council:guiding-policy.adoc

URL redirecciona

Puede crear una redirección desde una página anterior a una nueva utilizando el atributo página-aliases. La sintaxis es la misma que para enlaces xref.

Example 1. In new-page.adoc

= Título de Página
:página-aliases: página-anterior.adoc

Además puede crear una redirección desde otro módulo o componente.

Ejemplo 2, en nueva-página.adoc

= Título de Página
:page-aliases: test-module:council:removed-page.adoc

Resalto de sintaxis

Puede añadir sintaxis resaltada a cualquier bloque origen estableciendo el atributo de lenguaje origen.

Ejemplo de establecer el atributo de lenguaje origen a un bloque de código

[,yaml]
----
salida:
  vaciar: cierto
  dir: ./público
  destinos:
  - proveedor: archivo
----

Ejemplo de bloque de código analizado con tal atributo

output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

The list of supported languages can be found in the highlight.bundle.js in the Fedora Docs UI.

Tablas de datos

Puede convertir una tabla usual a unas DataTables utilizando el atributo de rol datatable. DataTables proporciona capacidades de filtro y ordenado.

Ejemplo de definición de una DatosTabla

|===
[.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%

Pueden ser utilizados roles adicionales para añadir características de DataTables:

dt-search: añade caja de búsqueda
dt-paging: añade paginación

Además puede alterar el estilo con la ayuda de clases de DataTables empotradas, tales como display o compact.

Ejemplo para utilizar opciones adicionales

|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
|===

Uso real de DataTables puede ser visto en la Documentación legal.

Bloquear tabuladores

Puede crear un conjunto de tabulados para organizar contenido de documentación dentro de un bloque.

Ejemplo para definir un conjunto tabulador [,asciidoc]

[tabs]
====
Tabulador A:: Contenido de Tabulador A.

Tabulador B::
+
Contenido de Tabulador B.

Tabulador C::
+
--
Contenido de Tabulador C.

Contenido de más de un bloque.
--
====

Resultado de conjunto de tabulador

Tab A
Tab B
Tabulador C

Contendios de Tab A.

Contenido de Tabulador B.

Contenido de Tabulador C.

Contenido de más de un bloque.

Para más información sobre tabuladores, refuera a la extensión Asciidoctor Tabs en https://github.com/asciidoctor/asciidoctor-tabs.

Tabla de contenido

Una tabla de contenido está generado automáticamente a la derecha de cada página.

IMPORTANTE: no hay ninguna necesidad de añadir el atributo `:toc:`como entonces será una tabla duplicada del contenido para el documento.

El lado derecho de la tabla solo exhibe niveles de título hasta el nivel 2 por defecto. Puede cambiar esta opción con el atributo page-toclevels.

= Título de Página
:page-toclevels: 3

Paginación

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.

= Título de Página
:page-pagination:

Puede ver un ejemplo vívido en esta página.

Macro de Botón y Menú de IU

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.

Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc and used in latest Quick Docs edited.

Esta opción está activada por el atributo experimental.

= Título de Página
:experimental:

Ejemplo de definir Botón Macro IU

. Pulse btn:[Crear].

. Elija una frase-contraseña que es fuerte pero además fácil de recordar en el diálogo que es exhibido.

. Pulse btn:[Aceptar] y la tecla se crea.

Ejemplos para definir Macro de IU de Menú

Para guardar el archivo, seleccione menu:Archivo[Guardar].

Seleccione menu:Vista[Zoom > Restablecer] para restablecer el nivel del zoom para el parámetro por defecto.

Mejores prácticas

Una recomendación breve cuando escriba unas páginas nuevas, o editando una existente.

Cabecera del documento

Todas las páginas deben iniciar con un nivel 1 título. [,asciidoc]

= Título de Página

Opcionalmente, puede añadir metadatos de autores y revisión.

Ejemplo 1 - Información de autores y revisión

= Título de Página
Ben Cotton; Peter Boy; Petr Bokoc 2.0, 26/11/2022: reparado para F37

Puede decidir omitir el número de versión, si no necesita esa información.

Ejempo 2 - Información de revisión sin versión

= Título de Página
François Andrieu 10/12/2022: ejemplo de metadatos de la revisión añadida

While these metadata are optional, try to keep at least the revision date so readers know how up-to-date the page is.

Example 3 - Revision date only

= Título de Página
Fedora Documentation Team 2022-12-10

Want to help? Learn how to contribute to Fedora Docs ›