El 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

Práctica hoja de trucos sobre el aspecto del marcado AsciiDoc. Utilícelo como referencia rápida para comprobar el formato, las listas, el contenido multimedia (imágenes y vídeo), el índice, etc.

Prácticas recomendadas de AsciiDoc

Buenas prácticas para escribir en AsciiDoc. Y lo que es más importante, tenga en cuenta que cada frase debe ir en su propia línea.

Fragmentos de Documentación Fedora

Cuando escriba Documentación de Fedora, algunas cosas surgen con frecuencia. Puede que no estén documentados en la documentación general de AsciiDoc, como en asciidoctor.org. + Esta sección contiene referencias útiles para que los escritores de la Documentación de Fedora copien y peguen en sus propios documentos AsciiDoc.

En esta sección, utilizaron la estructura de repositorio como un ejemplo:

Ejemplo de estructura de documentación del repositorio
📄 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 Define el componente de documentación como test-module (atributo name)

Mismo repositorio

Utiliza la ruta local relativa para el directorio paged en el mismo módulo.

Enlace para un página en el nivel raíz
xref:another-page.adoc
Enlace a una página dentro de unsubdirectorio pages+
xref:sub-dir/rules.adoc

Como un enlace interno, pero utilice un dos puntos (:) para separar el nombre del módulo. Si no está seguro si no necesita esto, ¡no lo quiera! Múltiples módulos vinculados en el mismo repositorio no está actualmente en un escenario común en la Documentación de Fedora.

Ejemplo 1
xref:council:guiding-policy.adoc

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.

Ejemplo 1. En 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
salida:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

La lista de idiomas admitidos se puede encontrar en la highlight.bundle.js en el IU de Fedora Docs.

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

  • Tabulador 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

Si tiene varias páginas que sigan el mismo tema, quizá es interesado en habilitar la paginación. La paginación + permite al lector navegar fácilmente a la página anterior o siguiente desde el árbol de navegación al añadir enlaces de navegación al final de la página.

Esta opción está activada por el atributo page-pagination.

= 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

Para mantener la consistencia en la presentación de un botón, vínculos de teclado, o un elemento de menú (ruta), las Macros de IU de Botón y Menú comunican al lector que acciones necesita tomar.

IMPORTANTE: aunque este atributo está nombrado experimental, las macros de IU son consideradas una característica estable de AsciiDoc y utilizada en el más último de los documentos Quick Docs editados.

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

Mientras estos metadatos son opcionales, intente conservar al menos la fecha de la revisión tal que los lectores conozcan como está al día la página.

Ejemplo 3: Revisión de fecha exclusivamente
= Título de Página
Equipo de Documentación de Fedora 10/12/2022

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