Funciones de Markdown
DocStatic utiliza Markdown como formato principal para la creación de contenidos. Puedes aprenderlo en diez minutos. Pero no es necesario, ya que el CMS proporciona un entorno completo de edición de texto enriquecido para metadatos, Markdown y componentes React.
Creación estructurada sencilla
Los temas en DocStatic tienen tres partes:
- Metadatos (en formato YAML)
- Contenido (en Markdown)
- Componentes React predefinidos.
El CMS se asegura de que los metadatos y Markdown se utilicen de forma coherente, mientras que los componentes React proporcionan un estilo uniforme y compatibilidad con las funciones de reutilización de contenido. No es necesario añadir ningún código JSX, ya que los componentes ya están disponibles globalmente.
Funciones estándar
Las funciones de Markdown incluyen:
- Estilos de caracteres en negrita, código, cursiva y tachado.
- Listas con viñetas y numeradas.
- Bloques de código.
- Niveles de encabezado (1 a 6).
- Reglas horizontales.
- Imágenes.
- Enlaces.
- Citas.
- Tablas simples.
Todas estas funciones se pueden seleccionar directamente desde la barra de herramientas de texto enriquecido del CMS.
A estas, Docusaurus añade:
- Advertencias
- Detalles (contenido expandible)
- Listas de tarjetas de documentación
- Pestañas
DocStatic amplía aún más estas funciones con:
- Fragmentos de código (de archivos)
- Comentarios
- Texto condicional
- Enlaces de ayuda contextual
- Diagramas
- Figuras
- Notas al pie
- Términos del glosario
- Ecuaciones matemáticas
- Fragmentos
- Variables
Front matter
El front matter se utiliza para añadir metadatos a tu archivo Markdown. Se proporciona en la parte superior del archivo, entre tres guiones ---. Los complementos de contenido pueden tener su propio esquema de front matter. DocStatic utiliza el front matter para:
- Condiciones (para texto condicional)
- Descripciones
- Slugs (rutas fijas)
- Etiquetas de taxonomía
- Títulos
- Estado del flujo de trabajo
Detalles
- Seleccione Detalles en la lista Incrustar.
- Edite el componente.
- Asigne un Resumen.
- Introduzca los Detalles.
Ejemplo:
Alternar
. Este es el contenido detallado.
Aquí puede utilizar Markdown, incluyendo texto en negrita y cursiva, y enlaces en línea.
Listas de tarjetas de documentación
Las listas de tarjetas de documentación se generan automáticamente para las categorías del índice. Sin embargo, también puedes añadirlas manualmente a un tema.
- Selecciona Lista de tarjetas de documentación en la lista Insertar.
- Dale un Título.
Para obtener más información, consulta Características de Markdown en la documentación de Docusarus.
Ejemplo:
📄️ MDX and React
DocStatic tiene soporte integrado para MDX, lo que te permite escribir JSX dentro de tus archivos Markdown y renderizarlos como componentes React. Sin embargo, si añades JSX directamente en tus temas, el CMS no podrá mostrarlos en el editor de texto enriquecido.
📄️ Tabs
El componente Pestañas le permite añadir contenido con pestañas a su tema.
📄️ Code blocks and snippets
DocStatic ofrece dos formas de incluir código en tu documentación. Ambas admiten el resaltado de sintaxis.
📄️ Admonitions
El componente Advertencias le permite añadir advertencias con estilo.
📄️ Headings and table of contents
En el CMS, puede seleccionar el nivel Párrafo o Encabezado (del 1 al 6).
📄️ Assets
A veces es posible que desee vincular activos (por ejemplo, archivos docx, imágenes, etc.) directamente desde los temas. DocStatic gestiona esto a través de la carpeta static/.
📄️ Markdown links
Hay dos formas de añadir un enlace a otra página: a través de una ruta URL o una ruta de archivo.
📄️ MDX plugins
MDX tiene un sistema de complementos integrado que se puede utilizar para personalizar la forma en que se analizan y transforman los archivos Markdown a JSX. Sin embargo, si cambia el comportamiento de Markdown, también debe reflejar estos cambios en el CMS.
📄️ Math equations
Las ecuaciones matemáticas se pueden representar utilizando KaTeX.
📄️ Diagrams
Los diagramas se pueden representar utilizando Mermaid en un bloque de código.
📄️ Head metadata
DocStatic establece automáticamente metadatos útiles para la página en `, y `.
📄️ Comments
El componente Comentario le permite añadir comentarios que son visibles en el CMS, pero no en la página renderizada, ni siquiera en el código fuente sin procesar.
📄️ Conditional text
El componente Texto condicional le permite envolver el contenido en un conjunto de condiciones que determinan cuándo debe mostrarse:
📄️ Context-sensitive help
«La ayuda contextual es un tipo de
📄️ Figures
(sin contenido fuente)
📄️ Footnotes
Existe una extensión de Markdown que proporciona notas al pie, pero su implementación no es consistente y separa el contenido del número. Por ejemplo:
📄️ Glossary terms
El componente Término del glosario le permite introducir una clave que se asigna a un término y una descripción localizados. El término se muestra subrayado. Al mover el cursor sobre el término, aparece el cursor de ayuda, y al pasar el cursor por encima, se muestra la descripción como una información sobre herramientas. En los dispositivos con pantalla táctil, al pulsar sobre el término se muestra una definición emergente.
📄️ Snippets
El componente Fragmento le permite reutilizar contenido en toda su documentación. Un fragmento es una parte de contenido que se puede insertar dentro de uno o más temas. Cuando realiza cambios en el fragmento, estos se aplican en todos los lugares donde se utiliza el fragmento. Esto puede resultar especialmente útil para el texto repetitivo. Los fragmentos tienen su propia colección en el CMS y se encuentran en una parte separada del repositorio.
📄️ Variable sets
El componente Variable le permite colocar una variable localizada en su texto.