Cargando



Como escribir con Markdown y sus diferencias con HTML.

Hablaremos de su syntax y como puede usarse para crear documentaciones bastantes completas para el área de sistemas.


oct 08 2015 18:43
Avanzado
oct 08 2015 21:04

De tu interés 👌

Qué es Markdown

Se define tanto como al software escrito en Perl, el cual convierte el texto escrito en HTML y adicionalmente, a la sintaxis utilizada para llegar al resultado HTML que esperamos. Una sintaxis pensada para ser sencilla para cualquiera que desee escribir en la web, sin necesidad de conocimientos de la misma.
Hoy en día la mayoría de los manejadores de contenido e incluso muchos clientes de correo, soportan el uso de la sintaxis Markdown, de manera nativa, esto con la intención de facilitar la creación de texto formateado sin la necesidad de implementar estilos o conocer de HTML. Estos manejadores utilizan un analizador o parser para convertir el texto escrito en Markdown a HTML.

MarkDown y la Documentación
Es muye útil aprender de markdown muchas herramientas de documentación; wikia, onenote, evernote, alfresco lo soportan de manera nativa, o con ayuda de terceros. Es importante tener documentación de los procesos y de posibles problemas, pero mas importante aun es mantenerla ordenada y limpia incluso desde la consola y markdown esta aquí para ayudarnos en ello.

Párrafos

Si estuviéramos escribiendo normalmente en un editor común, para definir un párrafo simplemente presionaríamos un par de:

Enter



Y veremos nuestro cursor ir un par de líneas más abajo para escribir en un párrafo nuevo.

En HTML se le conoce como <p> de párrafo.

En Markdown es tan fácil como en un editor normal.

Adicionalmente tenemos la ventaja de que un único salto de línea no, separa el texto en múltiples líneas, si escribimos algo así:
Un texto.
Otro texto.
Se verá así:
Un texto. Otro texto.
Usar múltiples líneas de separación se reduce igualmente a un único espacio de separación entre los párrafos

Encabezados

En un editor normal necesitaríamos de la barra de herramientas para definir un estilo de encabezado para un texto, o si te sientes un poco desordenado bastaría con subirle al tamaño de la fuente y ponerlo en negrita.

En HTML se les conoce como <h1>, <h2>, etc, de header.

En Markdown es muy sencillo, simplemente debes colocar el carácter numeral (#) de prefijo al encabezado, mientras más de estos tenga de menor grado será el encabezado hasta un máximo de 6.

Por ejemplo un encabezado <h1> (el más grande) y uno <h3> se escribirían así:
# Gran encabezado

### Pequeño encabezado
y el resultado sera así.


Gran encabezado

Pequeño encabezado



Separadores

Los separadores normalmente no son posibles de dibujar en editores sencillos.



En HTML se convierten en <hr> de horizontal rules.

Se delimitan al escribir 3 o más asteriscos o guiones. Pueden estar seguidos o separados por un espacio, es indiferente.
* * *
***
- - -
---
Énfasis

Este formateado es el conocido como itálico y negrita.

En HTML sería <em> y <strong>.
Para crear texto con formato itálico tan solo debes rodear el texto entre simples asteriscos o subguiones, y para negrita entre dobles:
*texto italico.*
_texto italico._
**texto negrita.**
__texto negrita.__
Se vería algo así:

texto italico. texto negrita.

Tachado

Este permite colocar texto como si lo estuviésemos tachando, utilizado mucho para control de versiones. o Bugs que fueron corregidos en una aplicación o sistema.

EN HTML sería <strike> de strikethrough.
Basta con rodear el texto entre doble virgulillas o tildes:
~~texto tachado.~~
Esta opción no es un estándar y puede que no funcione en todos los editores.

Citas

El estilo de cita normalmente no se encuentra de manera fácil en un editor de texto común

En HTML sería <blockquote>.

Solo debemos colocar el carácter de "mayor que" (>) como prefijo al texto que le sigue (similar al direccionamiento en linux)
> Esta es una cita.
Se vería:

Esta es una cita.



Listas

Para definir una lista de objetivos solemos utilizar la funcionalidad de viñetas para listas sin orden especifico y listas numeradas.
En HTML sería <ul> para listas sin orden, <ol> para listas ordenadas y <li> para definir cada ítem de la lista.
En Markdown las definimos simplemente prefijando cada ítem con un asterisco (*), guión (-) o símbolo de más (+) para listas sin orden. Para listas ordenadas prefijamos con el número que le corresponde y un punto:
* Escribir tutorial
* Publicarlo en Solvetic.
1. Nuevo Tutorial.
3. Elegir una sección y nivel.
2. Corregir formatos y publicar.
Se vería así:
  • Escribir tutorial.
  • Publicarlo en Solvetic.
  • Nuevo Tutorial.
  • Elegir una sección y nivel.
  • Corregir formatos y publicar.
En lista enumeradas no se respeta la jerarquía del numero, se usara la posición dentro de ellas.

Enlaces

Colocar enlaces es sumamente útil e importante ya que permite referenciar contenido a alguna documentación externa o un tutorial.

Ejemplo:
Se ha asegurado el servidor Nginx con fail2ban usando el [tutorial-solvetic](http://www.solvetic.com/tutoriales/article/1963-instalar-fail2ban-y-asociarlo-con-ssh-y-nginx/)
Colocamos entre corchetes [] el texto que queremos tenga el enlace y seguidamente colocamos entre paréntesis () el enlace de destino.

Si prefieres hacerlo de una manera más ordenada que tener las referencias en el medio de tu texto puedes hacerlo también de la siguiente manera:
Se ha asegurado el servidor Nginx con fail2ban usando el[1]...
...
...
    [1]: http://www.solvetic.com/tutoriales/article/1963-instalar-fail2ban-y-asociarlo-con-ssh-y-nginx/
Otra opción seria:
Se ha asegurado el servidor Nginx con fail2ban usando [fail2ban-nginx-solvetic]...
...
...
    [ssh-nginx-solvetic]: http://www.solvetic.com/tutoriales/article/1963-instalar-fail2ban-y-asociarlo-con-ssh-y-nginx/
Ahora añadir imágenes.


Imágenes

Podemos añadir imagenes de manera casi similar a los enlaces añadiendo un ! antes de cada una, debo destacar no poder verlas desde una terminal, bueno no de manera directa.
![texto alterno](url-de-imagen)
Podemos usar las mismas opciones de los enlaces si queremos tenerlo mas ordenado.

Tablas

Acostumbro a colocar datos de acceso en tablas de servidores o servicios.

Para ello dibujamos las líneas de la tabla con pipes (|) para delimitar las columnas y guiones (-) para separar el encabezado del resto de las filas:
| Servicio    | Usuario | Clave     |
|-------------|---------|-----------|
|   FTP       |solvetic |aw-D.wak   |
|   SSH       | admin   |2-.-am,    |
Tendríamos algo así:


tablas.png


No es necesario que los pipes estén alineados, y los "bordes" son opcionales, por ejemplo:
Encabezado 1 | Encabezado 2
---|---
probemos | algo
probemos alguna | otra cosa
Esto generaría la misma tabla.
También puedes alinear el texto de tus columnas colocando el símbolo de dos puntos (:) en el separador hecho con guiones del lado que deseas que esté alineado:
| Alineado a la izq. | Centrado | Alineado a la der. |
|:-------------------|:--------:|-------------------:|
| prueba			 | prueba   | prueba			 |
No todos los editores de aceptan las tablas en Markdown.

Codigo

Podemos resaltar nuestro codigo con markdown y diferencia de un lenguaje a otro.

Sintaxis de triple backtick


Colocar este tipo de bloques es muy fácil, solo debemos encerrar el bloque de código que deseamos entre 3 backticks (```) seguido del nombre del lenguaje al que pertenece el código que deseas colocar:
```lenguaje
x = y
...
```
Un ejemplo de código en JavaScript sería algo así:
```js
function test() {
   console.log('testing!')
}
```
Esto generaría un agradable bloque de código con syntax resaltada para javascript:
function test() {
  console.log('testing!')
}

Sintaxis de pre-espaciado


Otra manera de colocar texto o código pre-formateado pero sin lenguaje especificado es "indentando" nuestro texto con 4 espacios, lo escribiríamos así:
     x = y
    //notemos que hay 4 espacios de separación entre el margen y lo que escribimos.
tendremos este resultado:
x = y
//notemos que hay 4 espacios de separación entre el margen y lo que escribimos.
El estándar solo acepta la opción con pre-espaciado.

Conclusiones
Un buen sistema de Documentación debe ser rápido, flexible y sencillo. Puntos que cubre de muy buena manera markdown, no debemos olvidar su syntax limpia para los ojos algo a tomar muy en cuenta si queremos revisar la documentación desde una terminal usando VIM/EMACS. La entrada tiene un enfoque para administradores de sistemas pero puede ser muy útil para todo tipos de profesionales o estudiantes espero haya quedado clara cualquier duda o sugerencia déjala en los comentarios.

¿Te ayudó este Tutorial?


2 Comentarios


Alex Pereiro
oct 10 2015 22:38

Me encantó Jonathan.


Teo Robles
oct 14 2015 17:58

+1

 

G

R

A

C

I

A

S

No esperes más y entra en Solvetic
Deja tus comentarios y aprovecha las ventajas de la cuenta de usuario ¡Únete!

X