Markdown

Markdown es un lenguaje de marcado ligero que permite estructurar y dar formato a documentos utilizando texto plano.

Los documentos Markdown utilizan habitualmente la extensión:

.md

Su sintaxis está diseñada para que el contenido resulte legible incluso sin procesarlo o visualizarlo mediante una aplicación específica.

Por ejemplo:

# Instalación

## Requisitos

Para instalar la aplicación necesitamos:

- Ubuntu 24.04
- conexión a Internet
- Git

## Instalación

Ejecutamos:

```bash
sudo apt update
```

Un visor compatible con Markdown interpreta los símbolos utilizados y muestra el documento con encabezados, listas, bloques de código y otros elementos de formato.

Markdown se utiliza ampliamente para crear documentación técnica, especialmente en proyectos de software y repositorios de código.

Encabezados

Los encabezados permiten organizar un documento en diferentes niveles.

Se crean utilizando el carácter #:

# Encabezado de nivel 1

## Encabezado de nivel 2

### Encabezado de nivel 3

#### Encabezado de nivel 4

El número de caracteres # determina el nivel del encabezado.

Los encabezados deben utilizarse siguiendo una estructura jerárquica.

Por ejemplo:

# Instalación
    ## Requisitos
    ## Procedimiento
        ### Ubuntu
        ### Windows
    ## Comprobación

No debemos elegir el nivel de un encabezado por su tamaño visual, sino por la posición que ocupa dentro de la estructura del documento.

Estructura del documento

Normalmente utilizaremos un único encabezado # como título principal del documento.

A partir de él organizaremos el contenido mediante ##, ### y los niveles que sean necesarios.

Párrafos

Los párrafos se escriben directamente como texto.

Este es el primer párrafo.

Este es el segundo párrafo.

Para separar dos párrafos dejamos una línea en blanco entre ellos.

Negrita y cursiva

Podemos destacar texto utilizando negrita:

**texto en negrita**

Para utilizar cursiva:

_texto en cursiva_

También podemos combinar ambos formatos:

**_texto en negrita y cursiva_**

El formato debe utilizarse para facilitar la lectura y destacar información relevante, evitando aplicarlo de forma innecesaria.

Listas

Markdown permite crear listas ordenadas y no ordenadas.

Listas no ordenadas

Podemos crear una lista utilizando -:

- Ubuntu
- Windows
- macOS

También podemos crear listas anidadas mediante sangrado:

- Sistemas operativos
  - Ubuntu
  - Windows
- Herramientas
  - Git
  - Visual Studio Code

Listas ordenadas

Las listas ordenadas utilizan números:

1. Crear el directorio.
2. Acceder al directorio.
3. Crear el archivo.
4. Editar el contenido.

Son especialmente útiles para documentar procedimientos en los que el orden de los pasos resulta importante.

Enlaces

Podemos crear un enlace utilizando:

[texto del enlace](URL)

Por ejemplo:

[Documentación de Ubuntu](https://documentation.ubuntu.com/)

En documentación técnica es recomendable que el texto del enlace describa el recurso al que conduce.

Por ejemplo, es preferible:

[Documentación de Git](https://git-scm.com/doc)

a:

[Haz clic aquí](https://git-scm.com/doc)

Imágenes

Las imágenes utilizan una sintaxis similar a los enlaces:

![texto alternativo](ruta-de-la-imagen)

Por ejemplo:

![Terminal de Ubuntu](images/terminal.png)

El texto situado entre los corchetes es el texto alternativo de la imagen y debe describir brevemente su contenido.

Es recomendable almacenar las imágenes utilizadas por la documentación en un directorio específico.

Por ejemplo:

technical-documentation/
├── images/
│   ├── installation.png
│   └── configuration.png
└── README.md

De esta forma podemos utilizar rutas relativas:

![Proceso de instalación](images/installation.png)

Capturas de pantalla

Cuando utilicemos capturas de pantalla en documentación técnica debemos comprobar que sean legibles y que no muestren información privada o sensible.

Las imágenes deben complementar la explicación, no sustituirla completamente.

Citas

Podemos crear una cita utilizando >:

> Este texto se mostrará como una cita.

También podemos utilizar varios párrafos o niveles cuando sea necesario.

Las citas pueden resultar útiles para reproducir una observación, advertencia o fragmento procedente de otra fuente.

Código

En documentación informática es frecuente incluir comandos, nombres de archivos, rutas o fragmentos de código.

Código en línea

Para incluir pequeños fragmentos dentro de una frase utilizamos una comilla invertida a cada lado.

Por ejemplo:

Utilizamos el comando `pwd` para mostrar el directorio actual.

También resulta útil para nombres de archivos o directorios:

Editaremos el archivo `README.md`.

Bloques de código

Cuando necesitamos mostrar varias líneas utilizamos un bloque de código.

Además, podemos indicar el lenguaje utilizado para obtener resaltado de sintaxis.

Por ejemplo, para Bash:

```bash
mkdir technical-documentation
cd technical-documentation
touch README.md
```

El resultado será:

mkdir technical-documentation
cd technical-documentation
touch README.md

Para JavaScript podríamos utilizar:

```js
const message = "Hello";
console.log(message);
```

El resultado será:

const message = "Hello";
console.log(message);

Para representar simplemente texto:

```text
technical-documentation/
├── images/
└── README.md
```

El resultado será:

technical-documentation/
├── images/
└── README.md

Bloques de código

Siempre que sea posible debemos indicar el lenguaje correspondiente después de los tres caracteres de apertura del bloque.

Esto facilita la lectura y permite aplicar resaltado de sintaxis.

Tablas

Markdown permite representar información estructurada mediante tablas.

Por ejemplo:

| Herramienta | Propósito                   |
| ----------- | --------------------------- |
| VS Code     | Edición                     |
| Git         | Control de versiones        |
| GitHub      | Alojamiento de repositorios |

El resultado será:

Herramienta	Propósito
VS Code	Edición
Git	Control de versiones
GitHub	Alojamiento de repositorios

Las tablas son útiles para presentar información que necesitamos comparar o consultar de forma estructurada.

No es recomendable utilizarlas cuando el contenido es demasiado extenso o complejo.

README.md

El archivo README.md se utiliza habitualmente como documento principal de un proyecto o repositorio.

Puede contener información como:

• nombre y descripción del proyecto;
• requisitos;
• instrucciones de instalación;
• instrucciones de utilización;
• estructura del proyecto;
• tecnologías utilizadas;
• referencias;
• información adicional necesaria para trabajar con el proyecto.

Una estructura sencilla podría ser:

# Nombre del proyecto

Breve descripción del proyecto.

## Requisitos

- requisito 1
- requisito 2

## Instalación

```bash
comando-de-instalacion
```

## Utilización

Descripción del procedimiento.

## Referencias

- [Documentación oficial](https://example.com)

No todos los archivos Markdown tienen que llamarse README.md.

Un proyecto puede contener diferentes documentos:

project/
├── README.md
├── installation.md
├── configuration.md
└── troubleshooting.md

Previsualización en Visual Studio Code

Visual Studio Code permite editar un archivo Markdown y visualizar el resultado generado.

Podemos abrir la previsualización mediante:

Ctrl + Shift + V

También podemos utilizar la paleta de comandos:

Ctrl + Shift + P

y seleccionar:

Markdown: Open Preview

Podemos mantener simultáneamente el archivo original y su previsualización para comprobar los cambios mientras escribimos.

Markdown, CommonMark y GitHub Flavored Markdown

Markdown fue creado como un lenguaje sencillo para escribir documentos utilizando texto plano.

Con el tiempo aparecieron diferentes implementaciones que introdujeron pequeñas diferencias y funcionalidades adicionales.

CommonMark proporciona una especificación precisa de una sintaxis común de Markdown:

CommonMark

GitHub utiliza una variante denominada GitHub Flavored Markdown (GFM), basada en CommonMark y ampliada con algunas funcionalidades.

Su documentación puede consultarse en:

GitHub Flavored Markdown

Por este motivo, determinadas características pueden funcionar de forma diferente dependiendo de la plataforma utilizada para procesar el documento.

Buenas prácticas

Cuando redactemos documentación técnica en Markdown tendremos en cuenta algunas recomendaciones:

• utilizar una estructura clara de encabezados;
• mantener una jerarquía coherente;
• utilizar nombres de archivo descriptivos;
• evitar documentos innecesariamente extensos;
• utilizar listas cuando faciliten la lectura;
• indicar el lenguaje de los bloques de código;
• utilizar rutas relativas para los recursos del proyecto;
• proporcionar texto alternativo para las imágenes;
• utilizar textos descriptivos en los enlaces;
• comprobar la previsualización del documento;
• mantener la documentación actualizada.

El objetivo no es utilizar todos los elementos disponibles en Markdown, sino crear documentación clara, sencilla de mantener y fácil de consultar.

Ejemplo de documentación

Un documento técnico sencillo podría tener el siguiente contenido:

# Instalación de Git

## Objetivo

Instalar Git en un equipo con Ubuntu 24.04 y comprobar que funciona correctamente.

## Instalación

Actualizamos la información de los repositorios:

```bash
sudo apt update
```

Instalamos Git:

```bash
sudo apt install git
```

## Comprobación

Comprobamos la versión instalada:

```bash
git --version
```

## Referencias

- [Git documentation](https://git-scm.com/doc)

Este tipo de estructura será la que utilizaremos progresivamente para documentar las prácticas del módulo de Sistemas informáticos.