markdown

Markdown

Fundamentos básicos

Seamos realistas: escribir contenido para la Web es tedioso. Los editores WYSIWYG ayudan a aliviar esta tarea, pero generalmente dan como resultado un código horrible o, peor aún, páginas web feas.

Markdown es una mejor manera de escribir HTML, sin todas las complejidades y fealdad que normalmente lo acompañan.

Algunos de los beneficios clave son:

  1. Markdown es fácil de aprender, con un mínimo de caracteres adicionales, por lo que también es más rápido escribir contenido.
  2. Menos posibilidades de errores al escribir en rebajas.
  3. Produce una salida XHTML válida.
  4. Mantiene el contenido y la visualización separados, para que no puedas estropear el aspecto de tu sitio.
  5. Escriba en cualquier editor de texto o aplicación Markdown que desee.
  6. ¡Es un placer utilizar Markdown!

John Gruber, el autor de Markdown, lo expresa así:

El objetivo primordial del diseño de la sintaxis de formato de Markdown es hacerla lo más legible posible. La idea es que un documento con formato Markdown se pueda publicar tal cual, como texto sin formato, sin que parezca que ha sido marcado con etiquetas o instrucciones de formato. Si bien la sintaxis de Markdown ha sido influenciada por varios filtros de texto a HTML existentes, la mayor fuente de inspiración para la sintaxis de Markdown es el formato del correo electrónico de texto sin formato. -- John Gruber

Grav viene con soporte integrado para Markdown y Markdown Extra. Debe habilitar Markdown Extra en su archivo de configuración system.yaml.

Sin más demora, repasemos los elementos principales de Markdown y cómo se ve el HTML resultante:

¡Marque esta página como favorita para consultarla fácilmente en el futuro!

Encabezados

Los encabezados desde h1 hasta h6 se construyen con un # para cada nivel:

# h1 Título
## h2 Título
### h3 Título
#### h4 Título
##### h5 Título
###### h6 Título

Representa a:

h1 Título

h2 Título

h3 Título

h4 Título

h5 Título
h6 Título

HTML:

<h1>h1 Título</h1>
<h2>Título h2</h2>
<h3>Título h3</h3>
<h4>h4 Título</h4>
<h5>h5 Título</h5>
<h6>h6 Título</h6>

Comentarios

Los comentarios deben ser compatibles con HTML.

<!--
este es un comentario
-->

El comentario a continuación NO debe verse:

Reglas horizontales

El elemento HTML <hr> sirve para crear una "ruptura temática" entre elementos a nivel de párrafo. En Markdown, puede crear un <hr> con cualquiera de los siguientes:

  • ___: tres guiones bajos consecutivos
  • ---: tres guiones consecutivos
  • ***: tres asteriscos consecutivos

se ve como:

Cuerpo (body)

El texto del cuerpo escrito de forma normal se envolverá como texto sin formato, con etiquetas <p></p> en el HTML renderizado.

Entonces este texto del cuerpo:

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis su ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

se representa en este HTML:

<p>Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis su ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.</p>

Se puede hacer un salto de línea con 2 espacios seguidos de 1 retorno.

HTML en línea

Si necesita una determinada etiqueta HTML (con una clase), simplemente puede usar HTML:

Párrafo en Markdown.

<div class="class">
     Esto es <b>HTML</b>
</div>

Párrafo en Markdown.

Énfasis

Negrita

Para enfatizar un fragmento de texto con un grosor de fuente mayor.

El siguiente fragmento de texto está representado en negrita.

**representado como texto en negrita**

se ve como:

representado como texto en negrita

y este es el HTML:

<strong>representado como texto en negrita</strong>

Cursiva

Para enfatizar un fragmento de texto en cursiva.

El siguiente fragmento de texto se representa como texto en cursiva.

_representado como texto en cursiva_

se ve como:

representado como texto en cursiva

y este es el HTML:

<em>representado como texto en cursiva</em>

Tachado

En GFM (Markdown con sabor a GitHub) puedes tachar.

~~Tacha este texto.~~

Que se ve como:

Tacha este texto.

y este es el HTML:

<del>Tachar este texto.</del>

Citas en bloque

Para citar bloques de contenido de otra fuente dentro de su documento.

Agregue > antes de cualquier texto que desee citar.

> **Fusion Drive** combina un disco duro con un almacenamiento flash (unidad de estado sólido) y lo presenta como un único volumen lógico con el espacio de ambas unidades combinado.

Representa a:

Fusion Drive combina un disco duro con un almacenamiento flash (unidad de estado sólido) y lo presenta como un único volumen lógico con el espacio de ambas unidades combinado.

y este es el HTML:

<blockquote>
   <p><strong>Fusion Drive</strong> combina un disco duro con un almacenamiento flash (unidad de estado sólido) y lo presenta como un único volumen lógico con el espacio de ambas unidades combinado.</p>
</blockquote>

Las citas en bloque también se pueden anidar:

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue.
Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>> Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. auctor hecho
Odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Representa a:

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. auctor hecho Odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Avisos

El antiguo mecanismo para avisos que anulan la sintaxis de comillas en bloque (>>>) ha quedado obsoleto. Los avisos ahora se manejan a través de un complemento dedicado llamado Markdown Notices

Listas

desordenado

Una lista de elementos en los que el orden de los elementos no importa explícitamente.

Puede utilizar cualquiera de los siguientes símbolos para indicar viñetas para cada elemento de la lista:

* bala válida
- bala válida
+ viñeta válida

Por ejemplo

+ Lorem ipsum dolor sit amet
+ Consectetur élite adipiscente
+ Entero molestie lorem en masa
+ Facilisis en pretium nisl aliquet
+ Nulla volutpat aliquam velit
   - Phasellus iaculis neque
   - Purus sodales ultricies
   - Vestibulum laoreet porttitor sem
   - Ac tristique libero volutpat en
+ Faucibus porta lacus fringilla vel
+ Eneos sit amet erat nunc
+ Eget porttitor lorem

Representa a:

  • Lorem ipsum dolor sit amet
  • Consectetur élite adipiscente
  • Entero molestie lorem en masa
  • Facilisis en pretium nisl aliquet
  • Nulla volutpat aliquam velit
    • Phasellus iaculis neque
    • Purus sodales ultricies
    • Vestibulum laoreet porttitor sem
    • Ac tristique libero volutpat en
  • Faucibus porta lacus fringilla vel
  • Eneos sit amet erat nunc
  • Eget porttitor lorem

Y este es el HTML

<ul>
   <li>Lorem ipsum dolor sit amet</li>
   <li>Consectetur adipiscing elit</li>
   <li>Entero molestie lorem en masa</li>
   <li>Facilisis en pretium nisl aliquet</li>
   <li>Nulla volutpat aliquam velit
     <ul>
       <li>Phasellus iaculis neque</li>
       <li>Purus sodales ultratricies</li>
       <li>Vestibulum laoreet porttitor sem</li>
       <li>Ac tristique libero volutpat en</li>
     </ul>
   </li>
   <li>Faucibus porta lacus fringilla vel</li>
   <li>Eneos sit amet erat nunc</li>
   <li>Eget porttitor lorem</li>
</ul>

Ordenado

Una lista de elementos en los que el orden de los elementos sí importa explícitamente.

1. Lorem ipsum dolor sit amet
2. Consectetur élite adipiscente
3. Lorem molestie entero en masa
4. Facilisis en pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Eneos sit amet erat nunc
8. Eget porttitor lorem

Representa a:

  1. Lorem ipsum dolor sit amet
  2. Consectetur élite adipiscente
  3. Lorem molestie entero en masa
  4. Facilisis en pretium nisl aliquet
  5. Nulla volutpat aliquam velit
  6. Faucibus porta lacus fringilla vel
  7. Eneos sit amet erat nunc
  8. Eget porttitor lorem

Y este es el HTML:

<ol>
   <li>Lorem ipsum dolor sit amet</li>
   <li>Consectetur adipiscing elit</li>
   <li>Entero molestie lorem en masa</li>
   <li>Facilisis en pretium nisl aliquet</li>
   <li>Nulla volutpat aliquam velit</li>
   <li>Faucibus porta lacus fringilla vel</li>
   <li>Eneos sit amet erat nunc</li>
   <li>Eget porttitor lorem</li>
</ol>

CONSEJO: Si solo usa "1." para cada número, Markdown numerará automáticamente cada elemento. Por ejemplo:

1. Lorem ipsum dolor sit amet
1. Consectetur élite adipiscente
1. Lorem molestie entero en masa
1. Facilisis en pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Eneos sit amet erat nunc
1. Eget porttitor lorem

Representa a:

  1. Lorem ipsum dolor sit amet
  2. Consectetur élite adipiscente
  3. Lorem molestie entero en masa
  4. Facilisis en pretium nisl aliquet
  5. Nulla volutpat aliquam velit
  6. Faucibus porta lacus fringilla vel
  7. Eneos sit amet erat nunc
  8. Eget porttitor lorem

Código

Código en línea

Envuelva fragmentos de código en línea con `.

En este ejemplo, por ejemplo, `<sección></sección>` debe incluirse como **código**.

Representa a:

En este ejemplo, <sección></sección> debe incluirse código.

Y la salida HTML es:

<p>En este ejemplo, <code>&lt;section&gt;&lt;/section&gt;</code> debe incluir <strong>code</strong>.</p>

Código sangrado

Sangrar varias líneas de código con al menos cuatro espacios, como en:

   // Algunos comentarios
   línea 1 de código
   línea 2 de código
   línea 3 de código

Representa a:

// Algunos comentarios
línea 1 de código
línea 2 de código
línea 3 de código

HTML:

<pre>
   <código>
     // Algunos comentarios
     línea 1 de código
     línea 2 de código
     línea 3 de código
   </código>
</pre>

Código de bloque "fence"

Utilice "vallas" ``` para bloquear varias líneas de código con un atributo de idioma

```
Texto de ejemplo aqui...
```

HTML:

<pre lenguaje-html>
   <code>Texto de muestra aquí...</code>
</pre>

Resaltado de sintaxis

GFM, o "GitHub Flavored Markdown" también admite resaltado de sintaxis. Para activarlo, simplemente agregue la extensión de archivo del idioma que desea usar directamente después del primer código "fence", ``js, y el resaltado de sintaxis se aplicará automáticamente en el HTML renderizado. Por ejemplo, para aplicar resaltado de sintaxis al código JavaScript:

```js
gruñido.initConfig({
   ensamblar: {
     opciones: {
       activos: 'docs/activos',
       datos: 'src/data/*.{json,yml}',
       ayudantes: 'src/custom-helpers.js',
       parciales: ['src/partials/**/*.{hbs,md}']
     },
     páginas: {
       opciones: {
         diseño: 'default.hbs'
       },
       archivos: {
         './': ['src/templates/pages/index.hbs']
       }
     }
   }
};
```

Representa a:

gruñido.initConfig({
   ensamblar: {
     opciones: {
       activos: 'docs/activos',
       datos: 'src/data/*.{json,yml}',
       ayudantes: 'src/custom-helpers.js',
       parciales: ['src/partials/**/*.{hbs,md}']
     },
     páginas: {
       opciones: {
         diseño: 'default.hbs'
       },
       archivos: {
         './': ['src/templates/pages/index.hbs']
       }
     }
   }
};

Para que funcione el resaltado de sintaxis, es necesario instalar y habilitar el Plugin Highlight. A su vez, utiliza un complemento jquery, por lo que jquery también debe cargarse en su tema.

Tablas

Las tablas se crean agregando barras verticales como divisores entre cada celda y agregando una línea de guiones (también separados por barras) debajo del encabezado. Tenga en cuenta que no es necesario alinear las barras verticalmente.

| Opción | Descripción |
| ------ | ----------- |
| datos | ruta a los archivos de datos para proporcionar los datos que se pasarán a las plantillas. |
| motor | motor que se utilizará para procesar plantillas. El manillar es el predeterminado. |
| extensión | extensión que se utilizará para los archivos de destino. |

Representa a:

Opción Descripción
datos ruta a los archivos de datos para proporcionar los datos que se pasarán a las plantillas.
motor motor que se utilizará para procesar plantillas. El manillar es el predeterminado.
extensión extensión que se utilizará para los archivos de destino.

Y este es el HTML:

<tabla>
   <cabeza>
     <tr>
       <th>Opción</th>
       <th>Descripción</th>
     </tr>
   </thead>
   <tcuerpo>
     <tr>
       <td>datos</td>
       <td>ruta a los archivos de datos para proporcionar los datos que se pasarán a las plantillas.</td>
     </tr>
     <tr>
       <td>motor</td>
       <td>motor que se utilizará para procesar plantillas. El manillar es el valor predeterminado.</td>
     </tr>
     <tr>
       <td>texto</td>
       <td>extensión que se utilizará para los archivos de destino.</td>
     </tr>
   </tbody>
</tabla>

Texto alineado a la derecha

Agregar dos puntos en el lado derecho de los guiones debajo de cualquier encabezado alineará a la derecha el texto de esa columna.

| Opción | Descripción |
| ------:| -----------:|
| datos | ruta a los archivos de datos para proporcionar los datos que se pasarán a las plantillas. |
| motor | motor que se utilizará para procesar plantillas. El manillar es el predeterminado. |
| extensión | extensión que se utilizará para los archivos de destino. |
Opción Descripción
datos ruta a los archivos de datos para proporcionar los datos que se pasarán a las plantillas.
motor motor que se utilizará para procesar plantillas. El manillar es el predeterminado.
extensión extensión que se utilizará para los archivos de destino.

Enlaces

Enlace básico

[Ensamblar](https://assemble.io)

Se renderiza en (pase el cursor sobre el enlace, no hay información sobre herramientas):

Ensambar

HTML:

<a href="https://assemble.io">Ensamblar</a>

Añade un titulo

[Upstage](https://github.com/upstage/ "¡Visita Upstage!")

Se renderiza en (pase el cursor sobre el enlace; debería haber información sobre herramientas) ):

Upstage

HTML:

<a href="https://github.com/upstage/" title="¡Visita Upstage!">Upstage</a>

Anclas con nombre

Los anclajes con nombre le permiten saltar al punto de anclaje especificado en la misma página. Por ejemplo, cada uno de estos capítulos:

# Tabla de contenido
   * [Capítulo 1](#capítulo-1)
   * [Capítulo 2](#capítulo-2)
   * [Capítulo 3](#capítulo-3)

saltará a estas secciones:

## Capítulo 1 <a id="chapter-1"></a>
Contenido del capítulo uno.

## Capítulo 2 <a id="chapter-2"></a>
Contenido del capítulo uno.

## Capítulo 3 <a id="chapter-3"></a>
Contenido del capítulo uno.

NOTA que la ubicación específica de la etiqueta de anclaje parece ser arbitraria. Están colocados en línea aquí porque parece discreto y funciona.

Imágenes

Las imágenes tienen una sintaxis similar a la de los enlaces, pero incluyen un signo de exclamación delante.

![Minion](https://octodex.github.com/images/minion.png)

Minion

o:

![Texto alternativo](https://octodex.github.com/images/stormtroopocat.jpg "El Stormtroopocat")

Texto alternativo

Al igual que los enlaces, las imágenes también tienen una sintaxis de estilo de nota al pie:

![Texto alternativo][id]

Texto alternativo

Con una referencia más adelante en el documento que define la ubicación de la URL:

 [id]: https://octodex.github.com/images/dojocat.jpg "El Dojocat"