Markdown es una familia de renderizadores.
CommonMark define un núcleo estable para párrafos, títulos, énfasis, enlaces, listas, citas en bloque y código. GitHub Flavored Markdown agrega tablas, listas de tareas, tachado y enlaces automáticos. Las notas al pie, las alertas, los emoji, el resaltado de sintaxis y las matemáticas dependen de las extensiones.
La misma fuente puede representarse de forma diferente en GitHub, sistemas de documentación, generadores estáticos, aplicaciones de notas y herramientas de correo electrónico. La portabilidad comienza con la identificación del renderizador de destino.
Construir una estructura duradera
- Utilice un H1 solo cuando el destino lo espere en el origen.
- Mantenga el orden lógico de H2 y H3.
- Escriba párrafos sin saltos de línea manuales innecesarios.
- Utilice bloques de código delimitados con una etiqueta de idioma.
- Mantenga estables los enlaces y las rutas de las imágenes.
- Haga que la fuente sea legible incluso cuando las extensiones desaparezcan.
Las tablas son útiles pero limitadas.
| Need | tabla de rebajas | Alternative |
|---|---|---|
| Comparación compacta | Good | None |
| Prosa larga en celdas. | Difícil de mantener | Encabezados o lista de definiciones |
| Separaciones de filas/columnas | No portátil | HTML donde esté permitido |
| Datos legibles por máquina | Weak | CSV/JSON más vista renderizada |
Las listas de tareas son notaciones, no una base de datos de proyectos.
La sintaxis de la lista de tareas es útil para listas de verificación, preparación para lanzamientos y plantillas de problemas. No proporciona propiedad, fechas de vencimiento, dependencias, recordatorios ni historial de auditoría. Traslade el trabajo operativo a un sistema de tareas cuando la responsabilidad sea importante.
Las notas a pie de página y las alertas dependen de las extensiones.
Las notas a pie de página mantienen las explicaciones secundarias fuera de la oración principal, pero no son CommonMark central. Las alertas GitHub agregan bloques de notas visuales, advertencias y precauciones; otros renderizadores pueden mostrarlas como comillas ordinarias. Escribe las palabras para que queden claras sin el estilo.
La mejora puede desaparecer. El significado debe sobrevivir.
Código y matemáticas
Utilice bloques de código delimitados con una sugerencia de idioma. La etiqueta controla el resaltado; no ejecuta código. No pegue secretos en ningún editor cuya ruta de datos no esté aprobada.
La sintaxis matemática depende de un renderizador como KaTeX. Los paquetes y comandos de LaTeX no compatibles no funcionarán automáticamente. Proporcione explicaciones en lenguaje sencillo sobre fórmulas importantes y verifique la accesibilidad en el resultado final.
Utilice el editor de rebajas de Jivaro
- Abra Markdown Editor y vista previa.
- Empiece en blanco, importe un archivo o utilice un ejemplo.
- Inspeccione la vista previa en vivo mientras escribe.
- Pruebe tablas, tareas, notas al pie, alertas, códigos, emojis y matemáticas por separado.
- Utilice el guardado automático como comodidad, no como única copia de seguridad.
- Exporte Markdown como maestro editable.
- Exporte HTML cuando se requiera salida renderizada.
- Abra el HTML exportado por separado e inspeccione enlaces, encabezados, códigos, tablas y matemáticas.
La exportación HTML necesita un límite de confianza
Si Markdown controlado por el usuario puede contener HTML sin procesar, desinfecte la salida antes de publicarla. Compruebe también si la exportación incluye estilo o solo HTML semántico; La salida pegada puede verse diferente en CSS de otro sitio.
Lista de verificación de portabilidad
Los títulos, enlaces, listas y códigos siguen siendo comprensibles.
Indique si se requieren GFM, notas al pie, alertas, emoji o matemáticas.
Mantenga los activos vinculados predecibles.
Valide la salida y la entrada que no sea de confianza.
El HTML renderizado no debería convertirse en la única copia editable.
El destino tiene autoridad.
Diseñar un perfil de compatibilidad
Para obtener documentación recurrente, anote el renderizador y las extensiones que admite. Un perfil GitHub podría permitir tablas y tareas GFM pero evitar HTML sin formato. Un sitio técnico puede agregar notas a pie de página, resaltado de sintaxis, alertas y KaTeX. Un perfil multiplataforma puede limitar el contenido a CommonMark más enlaces ordinarios y código delimitado.
Ejecute el mismo documento de dispositivo a través de cada renderizador compatible después de las actualizaciones. El dispositivo debe contener listas anidadas, barreras de código, una tabla, enlaces, imágenes, Unicode, notas a pie de página, alertas y matemáticas. Las diferencias se hacen visibles antes de que afecten la documentación publicada.
Versión de imágenes y archivos vinculados con la fuente.
Las imágenes rotas y las descargas a menudo provienen de mover Markdown sin sus recursos. Utilice rutas relativas predecibles, nombres de archivos descriptivos, dimensiones intrínsecas en el HTML generado y un verificador de enlaces. Cuando un documento se exporta o copia a otra plataforma, verifique que cada activo local haya sido transferido o reemplazado con un URL canónico absoluto.
Preguntas frecuentes
No. Normalmente se suministran mediante extensiones como GitHub Flavored Markdown.
No. Otros renderizadores pueden mostrarlos como comillas en bloque ordinarias o sintaxis no compatible.
No. El HTML sin procesar y el HTML generado deben desinfectarse de acuerdo con el modelo de confianza del destino.
Sigue siendo más sencillo editar, versionar y pasar a otro renderizador.
Aplicaciones relacionadas Jivaro
Escribe, busca, previsualiza, importa, guarda automáticamente y exporta Markdown con CodeMirror, desplazamiento sincronizado, diagramas Mermaid, frontmatter, tablas, resaltado de sintaxis y matemáticas.
Abrir aplicaciónFuentes y referencias
- CommonMark EspecificaciónCommonMark · referencia
- Especificación de rebajas con sabor a GitHubGitHub · referencia
- Sintaxis de escritura y formato de GitHubGitHub Docs · referencia
- KaTeX Funciones soportadasKaTeX · referencia
- Editor y vista previa de MarkdownJivaro · propio