Markdown separa el origen de la presentación
Un archivo Markdown es texto ordinario, normalmente guardado con la extensión .md. El origen sigue siendo comprensible sin una aplicación especial, mientras que GitHub, las herramientas de documentación, los generadores de sitios estáticos y los editores pueden renderizarlo con tipografía y navegación.
Esa separación es la idea central: los autores describen el significado con un vocabulario reducido y el destino decide cómo se ve el resultado. El mismo README puede resultar cómodo en una terminal, en una revisión de código y en un sitio de documentación pulido.
# Deploying the API Run the **smoke tests** before release. - Verify health checks - Review error rates - Tag the build
Por qué Markdown funciona bien para la escritura técnica
Markdown reduce al mínimo la distancia entre escribir y revisar. El origen contiene poco ruido visual, los cambios producen diffs útiles por líneas y los archivos pueden vivir junto al código o la configuración que explican.
- Portable: el texto plano no depende de un único proveedor o editor.
- Diferenciable: los cambios son fáciles de inspeccionar en el control de versiones.
- Componible: las herramientas de documentación pueden transformarlo en HTML, PDF o contenido de ayuda.
- Legible: el origen es útil incluso antes de ser renderizado.
- Automatizable: los scripts pueden revisar enlaces, encabezados, ejemplos y convenciones de estilo.
Markdown tiene una sintaxis básica y varias variantes
El núcleo común cubre párrafos, encabezados, énfasis, enlaces, imágenes, citas, listas y código. Las plataformas suelen añadir extensiones. GitHub Flavored Markdown, por ejemplo, popularizó las tablas, las listas de tareas y el tachado en los flujos de trabajo de los desarrolladores.
Las extensiones son útiles, pero la portabilidad sigue importando. Un encabezado sencillo funciona casi en cualquier lugar; un bloque de diagrama específico de una plataforma puede no hacerlo. Cuando un documento debe moverse entre herramientas, prueba la sintaxis en el destino y conserva el significado importante en texto ordinario.
Dónde aparece Markdown
Markdown es habitual allí donde el contenido debe mantenerse cerca del software o moverse por un flujo de trabajo basado en texto. También es útil fuera de la ingeniería cuando un origen duradero y de baja fricción vale más que un maquetado de página preciso.
- Archivos README, guías de contribución, changelogs y notas de versión
- Referencias de API, tutoriales, runbooks y registros de decisiones de arquitectura
- Descripciones de incidencias, pull requests, comentarios y bases de conocimiento del equipo
- Sitios web estáticos, blogs, documentación de producto y manuales internos
- Notas o documentos convertidos que necesitan limpieza antes de publicarse
Para qué no está diseñado Markdown
Markdown no es un formato de maquetado de páginas. Las fuentes exactas, las columnas, los objetos flotantes, la paginación para impresión y los componentes interactivos complejos pertenecen a otros sistemas. Un PDF o una presentación convertidos conservarán el texto útil con más facilidad que su composición visual.
Tampoco es automáticamente seguro por el simple hecho de ser texto plano. Los renderizadores deben tratar los enlaces y el HTML sin procesar opcional como no confiables. Un buen editor higieniza la salida de la vista previa y una canalización de publicación aplica su propia política de seguridad.