Guía básica Markdown

Markdown es un lenguaje de etiquetado como lo es HTML, solo que tiene una forma más sencilla de ser usado ya que no tenemos que recordar muchas etiquetas, y no necesitas de un navegador para entender totalmente el contenido de un archivo.

Según lo que he escuchado la idea principal de Markdown era ser una competencia para HTML poder remplazarlo, y la verdad es que es mucho más práctico y fácil de hecho se puede decir que el 90% (opinan mía, de la mayoría de proyectos que he visto, no es un dato muy verídica) de la documentación de Github está escrita en Markdown.

Como usarlo

Para usarlo solo hasta con descargar algún editor de Markdown.

Básicamente atom o visual studio code se me hacen muy buena opción, este artículo por ejemplo está escrito en visual studio code, que es el editor que últimamente estoy probando.

Encabezados

Los encabezados son aquellos títulos, son lo que son las etiquetas <h1> , <h2>, <h3>, entre otros...

Código:


# Encabezado H1 #
## Encabezado H2 ##
### Encabezado H3 ###
#### Encabezado H4 ####
##### Encabezado H5 #####
###### Encabezado H6 ######

Salida:

Encabezado H1

Encabezado H2

Encabezado H3

Encabezado H4

Encabezado H5

Encabezado H6

Párrafos y saltos de línea

Para generar un párrafo es tan sencillo como escribir y al terminar el párrafo dar dos veces a enter

Código:


Esto es un párrafo: bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla

Salida:

Esto es un párrafo: bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla

Al igual que sucede con HTML, Markdown no soporta dobles líneas en blanco, así que si intentas generarlas estas se convertirán en una sola al procesarse, es decir:

Código:


Esto 
esta
escrito
en 
varias
líneas

Salida:

Esto esta escrito en varias líneas

Para realizar un salto de línea y empezar una frase en una línea siguiente dentro del mismo párrafo, tendrás que pulsar dos veces la barra espaciadora antes de pulsar una vez intro.

Código:


Esto  
esta  
escrito  
en  
varias  
líneas

Salida:

Esto
esta
escrito
en
varias
líneas

Blockquote o citas

Para generar blockquote o citas se utiliza el carácter mayor que > al comienzo del bloque de texto.

Código:


> esto es una cita — por mi

Salida:

esto es una cita — por mi

Podemos crear un bloque de citas usando en cada línea el símbolo mayor que > , también se puede crear una cita dentro de otra.

Código:


> esto es una cita en una línea
> > esto es otra cita dentro de la cita
> > > esta es una cita de la cita de la cita.
>
> cita principal

Salida:

esto es una cita en una línea

esto es otra cita dentro de la cita

esta es una cita de la cita de la cita.

cita principal

Es importante colocar el mayor que > después de la cita interna, si no la línea siguiente no se mostraría en pantalla.

Listas

Para crear listas sin un orden en específico, es tan sencillo como usar cualquiera de estos símbolos -, + o *

Código:


- ítem 1
* ítem 2
+ ítem 3

Salida:

ítem 1

ítem 2

ítem 3

Como se puede observar no importa cual símbolo se escoja o si se usan de forma aleatoria, siempre se mostrara de la misma forma.
Para generar listas anidadas basta con agregar cuatro espacios en blanco o mejor aún una tabulación antes del siguiente símbolo.

Código:


+ ítem 1
    + ítem 1.1
        + ítem 1.1.1
+ ítem 2
    + ítem 2.1

Salida:

ítem 1
- ítem 1.1
  - ítem 1.1.1
ítem 2
- ítem 2.1

Para crear listas ordenadas solo debemos usar la sintaxis de tipo número 1. o cualquier_número. es importante siempre poner el punto después del número.
Al Igual que en las listas desordenadas usamos el mismo método para realizar las anidaciones.

Código:


1. ítem 1
2. ítem 2
    1. ítem 2.1
    2. ítem 2.2
        1. ítem 2.2.1
3. ítem 3
    + ítem

Salida:

ítem 1
ítem 2
1. ítem 2.1
2. ítem 2.2
  1. ítem 2.2.1
ítem 3
- ítem

Cómo puedes ver se puede usar listar ordenadas y desordenadas en la misma lista.

Bloques de código

Los bloques de código son usados para escribir código fuente, para producir un bloque de código sin ningún tipo de formato basta con dar un tab o poner 4 espacios en blanco

Código:


    import abc
    print ("hola")

Salida:

import abc
print ("hola")

Aunque en la documentación oficial no vi o no encontré la referencia para resaltar un Code Highlighting o destacamento de código.

Sin embargo debido a la naturaleza de Markdown se han producido variantes y mutaciones que agregan sintaxis diferentes.

La sintaxis para crear cuadros de código es la siguiente ``` y ~~~ también he visto referencias donde después de la tabulación se usa ::: seguido del lenguaje usado. sin embargo este último no lo he podido comprobar. (En mi caso particular uso el primero)

Código:


    ```python
    import abc
    print ("hola")
    ```

Salida:


import abc
print ("hola")

Si observaron use la palabra python después de los ``` de esta forma se puede destacar el código.

Reglas Horizontales

Las reglas horizontales son aquellas divisiones visuales que se hacen a las secciones de echo en este artículo ya has visto varios (la línea que está debajo de cada Código: y Salida:) para hacerlos se utilizan * * *, - - - o _ _ _

Código:


    * * *
    - - -
    _ _ _

Salida:

Al igual que las listas, cualquier símbolo que decidamos usar generara la misma visualización.

Énfasis (negritas y cursivas)

Simplemente tendrás que envolver palabras o textos en éstos símbolos para conseguir cursivas o negritas.

Código:


*cursiva*  
_cursiva_  
**negrita**  
__negrita__  
***cursiva y negrita***  
___cursiva y negrita___

Salida:

cursiva
cursiva
negrita
negrita
cursiva y negrita
cursiva y negrita

Links

Son los enlaces que conocemos se crean escribiendo la palabra o texto enlazada entre [] corchetes, y el link en cuestión entre () paréntesis, para ser exacto se debe escribir [](), todo pegado.

Código:


[Ocitronix](https://kiryeelesion.blogspot.com.co/ )

Salida:

Ocitronix

Se puede agregar un título al enlace, lo que quiere decir que al situar al cursor sobre el link se observara el título que le designemos.

Código:


[Ocitronix](https://kiryeelesion.blogspot.com.co/ "Visita Ocitronix")

Salida:

Ocitronix

Links de referencia

Se realiza con [][] será más sencillo viendo un ejemplo.

Código:


Visita mi [Blog][1] o mi canal de [YouTube][2]

Bla  
bla  
bla  
...  
...

[1]: https://kiryeelesion.blogspot.com.co/ "Ocitronix"
[2]: https://www.youtube.com/channel/UCcAGsC7H02dhT4QVi0L-smg/featured "Tronix"

Salida:

Visita mi Blog o mi canal de YouTube

Bla
bla
bla
...
...

Como pueden observar las referencias no se muestran al momento de visualizarlo lo que nos sirve para acomodarlo es una zona en cualquier parte del documento.

Links automáticos

Para generar links automáticos solo deben ser rodeados por los símbolos <>.

Código:


<https://kiryeelesion.blogspot.com.co/>

Salida:

https://kiryeelesion.blogspot.com.co/

Aunque la verdad me ha sucedido que al solo colocar el enlace se ha publicado como un link normal.

Imágenes

Si sabes agregar un link sabes agregar una imagen, debido a que se usa la misma sintaxis solo que se antepone un símbolo de ! antes de primer [] y el enlace dentro de () será ruta de la imagen.

Código:


![Imagen](https://3.bp.blogspot.com/-mkzq5ruVCkI/V5wyUOdnI4I/AAAAAAAAXEY/IMtIG1HDgVo71hpFyZk6aBeZO-3kxCQBQCLcB/s1600/pcbnew.png)

Salida:

Al igual que los links, se puede agregar un texto alternativo a la imagen con la misma sintaxis, así cuando posiciones el mouse encima de la imagen veras el texto

Código:


![Imagen1](https://3.bp.blogspot.com/-mkzq5ruVCkI/V5wyUOdnI4I/AAAAAAAAXEY/IMtIG1HDgVo71hpFyZk6aBeZO-3kxCQBQCLcB/s1600/pcbnew.png "Como instalar kicad")

Salida:

También es posible acceder a recursos locales, Es decir si quieres hacer notas que no necesariamente subirás a una página web puedes realizar el documento sin problemas, por Ejemplo: Este articulo está en una carpeta llamada Markdown que es la raíz del proyecto por decirlo de alguna forma, dentro de esta carpeta está el archivo markdown.md y un archivo de imagen llamado LOGO.PNG, para mostrar esta imagen haremos lo siguiente:

Código:


![Imagen2](LOGO.PNG "Tronix")

Salida:

Ahora supongamos que por cuestión de orden decidimos tener una carpeta llamada imágenes y dentro tenemos un archivo llamado blog.png.

Código:


![Imagen3](/Imagenes/blog.png "Blog")

Salida:

En conclusión dentro de la sintaxis lo que tenemos que pasar es la ruta de la imagen a mostrar se un enlace web o un recurso local.

Videos

Bueno llegados a este punto, tengo que decir que no es tan fácil como en el caso de las imágenes, de hecho no hay referencia en la documentación oficial acerca de este tema, en otros sitios encontré algo parecido a un macro en el cual deberías de escribir [[embed url=http://www.youtube.com/el_video]], lo malo es que es solo compatible con videos de YouTube, y la verdad no he conseguido que funcionara sin necesidad de instalar algo adicional.

Para solucionar esto podemos recurrir a un enlace que te lleve al video pero que este contenido en una imagen del mismo, es decir:

Código:


[![video](https://i.ytimg.com/vi/0AqI4P7wfs0/hqdefault.jpg?sqp=-oaymwEXCPYBEIoBSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAfCtLwNOXwG8ZnIGZC0Z9O6Zqyzw)](https://www.youtube.com/watch?v=0AqI4P7wfs0&t=1s "clic para ver el video")

Salida:

Al dar clic en la imagen te redirecionara al video que quieras mostrar desde la página que desees.

Tablas

Para crear una tabla basta con utilizar pipes and dashes (tuberías y guiones, rayas al fin de cuentas)

Código:


Primer título | Segundo título | Tercer título |
------------- | -------------  |---------------|
Contenido     | contenido      | más contenido |
Contenido     | Contenido      | contenido     |

Salida:

Primer título	Segundo título	Tercer título
Contenido	contenido	más contenido
Contenido	Contenido	contenido

Es bastante facil crear tablas, ademas dentro del contenido acepta sintaxis mardown, podremos utilizar en nuestras tabalas negritas, cursivas, links, imagenes, entre otros.

Backslash Escapes

Markdown te permite usar el símbolo de backslash para omitir su sintaxis en casos especiales, por ejemplo quieres que se vea en pantalla una palabra entre asteriscos, *una palabra* pero se visualiza una palabra, debido a que los asteriscos son la sintaxis para las cursivas.

Para hacer esto solo debes usar el carácter \ antes del símbolo que deseas utilizar.

Código:


\*una palabra\*

Salida:

*una palabra*

Markdown provee escapes para los siguientes caracteres

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
!exclamation mark

En conclusion, se puede decir que es una forma facil y rapida de realizar documentacion y notas vitaminadas, es mejor que usar una suit de ofimatica sobretodo cuando documentas codigo, ahora bien aunque se puede ver algo limitado en funciones, lo cierto es que encontraras plugisn para poder usar formulas matematicas usando una sintaxis similar a la de latex y demas extenciones que ampliaran un poco el uso de esta herramienta, sin duda alguna algo que hay que probar