Markdown, solución a la documentación de proyectos

Hace poco tuve que trabajar en 3 versiones paralelas de una misma aplicación. No hubo mayor problema porque lo hicimos con un sistema de control de versiones. Se generaron 3 «branches» o ramas y se «mergeo» o se unió el código de las 3 en la rama master.

El problema lo tuvimos a la hora de tocar de forma paralela la documentación del proyecto. Estaba escrita en un fichero .doc en un directorio externo al versionado del código. ¿Qué ocurrió? Lo lógico y esperado … Se modificó la documentación perdiendo los cambios de los branches anteriores.

Esto no nos hubiese pasado si la documentación estuviera escrita con Markdown y versionado igual que el código.

Qué es Markdown

Markdown es un lenguaje de marcado ligero (creado por John Gruber y ayudado por Aaron Swartz) que facilita la aplicación de formato a un texto.

Se creó como herramienta de conversión del texto plano a Html pero se usa para muchas más cosas.

Tiene licencia BSD, es decir, se distribuye libremente

Ventajas Markdown

Vamos a ver que ventajas  puede tener el uso de Markdown

  • Es fácil de leer: Es texto plano con algun caracter especial para darle formato
  • Es compatible con cualquier dispositivo: Es texto plano asi que podremos abrirlo en la mayoría e dispositivos. No necesitamos software dependiente
  • Es más rápido y ágil que otras soluciones: Al ser texto plano es muy ligero
  • Fácil de aprender
  • Puedes escribir Html al mismo tiempo: Markdown es capaz de interpretar el texto plano con formato o html
  • Es dificil cometer errores: Su sintaxis es fácil por lo que es dificil cometer errores como en Html

Sintaxis Markdown

Os cuento algunos ejemplos de su sintaxis:

Cabeceras

Podemos formatear cabeceras con Markdown añadiendo el caracter #

Equivalente a usar <h1><h2><h3> … en Html

Negrita

Podemos formatear un texto en negrita añadiendo **

Equivalente al tag <b> de html

** Soy un texto en negrita **

Cursiva

Podemos formatear el texto en cursiva añadiendo _

Equivalente al tag <i> de html

_Soy un texto cursiva_

Listas desordenadas

Las listas desordenadas se formatean con el simbolo + y –

Es equivalente al tag <ul><li> de Html

+ Elemento 1
+ Elemento 2
Elemento 2.1
Elemento 2.2
Elemento 2.3

Listas Ordenadas

No hace falta ninguna explicación, se ordenan mediante números.

Equivale a utilizar <ol><li> en html

1. Elemento 1
2. Elemento 2
3. Elemento 2.1
4. Elemento 2.2
5. Elemento 2.3

Enlaces

Se utilizan corchetes para el texto y paréntesis para el enlace. Equivalente a <a href de Html

[texto](http://www.limni.net)

Imágenes

Similar a los enlaces pero añadiendo el caracter !

Equivalente a <img src de Html

![Texto de la imagen](/ruta/imagen.jpg)

Podeis consultar el resto de sintaxis : Cheat Sheet Markdown

Herramientas con soporte para Markdown

Tenemos muchas herramientas para trabajar con Markdown, similares todas ellas. La mayoria de ellas permiten exportar el texto en Html y en Pdf y presentan previsualización en linea.

  • WriteMonkey: Editor de textos, solo para Windows y necesita tener instalado .Net 4.0 . Te permite escribir texto con formato Markdown y después exportarlo como Html o como texto enriquecido.
  • Markdownpad: Compatible con Windows. Te permite escribir texto y ver el resultado al mismo instante en formato Html

markdown

  • Dingus: Es la herramienta desarrollada por John Gruber para trabajar con Markdown. Nos permite trabajar online
  • Markable: Editor online con autoguardado, exportación a Html, previsualización del texto. Se integra con Evernote y Dropbox
  • Byword: Editor de textos compatible con Mac para escribir texto en formato Markdown. No es gratuita cuesta 11.99€. Se sincroniza con todos tus dispositivos a través de iCloud y Dropbox. Permite exportar en Html y Pdf. Permite publicar en plataformas web de forma inmediata.
  • MdCharm: Editor de textos multiplataforma y gratuito. Tiene previsualización del texto escrito y exportación a Html o PDF. Además tiene soporte para MarkdownExtra y Multimarkdown.

Markdown

  • MOU: Editor de texto con soporte Markdown. Compatible con MAC y gratuito.
  • UberWriter: Editor de texto con soporte Markdown de código abierto y gratuito. Permite exportar a .ODT, PDF, Html
  • Retext: Editor de texto con soporte Markdown compatible con distribuciones Linux y gratuito.

Como veis hay un monton de soluciones, solo hay que escoger la que mejor se adapte a nuestro equipo y a nuestras necesidades.

Post By Rocio Muñoz (37 Posts)

Ingeniera Informatica. Dicen que todos los niños nacen con un pan debajo del brazo ... Yo creo que llevaba un ordenador. Trabajo como programadora en Cic en entornos Java. Apasionada del mundo web y la innovacion social.

Connect

No comments yet.

Deja un comentario

Leave your opinion here. Please be nice. Your Email address will be kept private.

Este sitio web utiliza cookies para que usted tenga la mejor experiencia de usuario. Si continúa navegando está dando su consentimiento para la aceptación de las mencionadas cookies y la aceptación de nuestra política de cookies, pinche el enlace para mayor información.plugin cookies

ACEPTAR
Aviso de cookies
Translate »