IronWoods.es

Desarrollo web

Blog / Documentación con Markdown

Markdown permite elaborar diversos documentos como páginas de descripción de un proyecto, currículos, etc. Lo más interesante es que podemos usar Markdown para crear documentos de varias páginas y enlazarlos entre sí.

El germen...

Tenía un documento Markdown que crecía y crecía y pensé ¿por qué no crear una documentación en varias páginas enlazadas como una web tradicional?

Y empecé a hacer pruebas con una pequeña estructura:

imagen del mapa de documentos Markdown
Mapa de navegación de la documentación Markdown

La estructura

La teoría es que los enlaces de Markdown funcionan como los de HTML, porque al final el intérprete de Markdown lo "convierte" para su visualización...

Escribir Markdown es mucho más sencillo que escribir HTML, y no tenemos CSS ni JavaScript, pero podemos crear una estructura para organizar las páginas, por ejemplo:

imagen de la estructura de documentos Markdown
Propuesta de estructura base para la documentación Markdown

De mi ordenador personal a la nube: todo "gratis"

Hay varios servicios online que usan Markdown para uno u otro propósito, por ejemplo, para documentar proyectos, como son bitbucket y github , cada uno tiene sus cosas... pero el documento que "lanzan" ambos es README.md. Podemos usar esto para crearnos una documentación navegable pública o privada en el propio repositorio, para lo que el documento README.md reemplazará al index.md de la estructura propuesta, en caso de que queramos cargar directamente la documentación, asimismo modificamos los enlaces en las páginas secundarias para que apunten a README.md.


Ejemplo en Github

Ejemplo en Bitbucket



28-02-2020

Entradas relacionadas:

Sitio libre de scripts. Solo efectos HTML / CSS