Ir al contenido

Herramientas

Guía de recursos

Todo lo que se puede usar al escribir una entrada, con el resultado y cómo se escribe cada cosa.

Esta entrada es una chuleta. Cada sección enseña un recurso tal y como se ve y, debajo, el código para escribirlo. El recuadro de Ficha de arriba y los bloques del final (Referencias, Relacionado, Mencionado en) salen solos del frontmatter: están explicados en Bloques automáticos.

Los componentes (<Aside>, <Tabs>, etc.) solo funcionan en archivos .mdx y hay que importarlos al principio, justo después del frontmatter:

Importar componentes
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

El título de la página sale del frontmatter (title) y la entradilla gris de description. Dentro del texto se usan ##, ### y ####. Los ## llevan una línea separadora encima y, junto con los ###, aparecen en el índice de la derecha.

Cómo se escribe
## Título de sección
### Subsección
#### Detalle

Un párrafo normal con negrita, cursiva, las dos, tachado, código en línea y un atajo de teclado como Ctrl + K. También hay superíndice (m2), subíndice (H2O) y texto resaltado.

Un salto de línea dentro del mismo párrafo se hace con una barra invertida al final
y el texto sigue en la línea siguiente.

Cómo se escribe
**negrita**, *cursiva*, ***las dos***, ~~tachado~~, `código en línea`
<kbd>Ctrl</kbd> + <kbd>K</kbd>
m<sup>2</sup>, H<sub>2</sub>O, <mark>texto resaltado</mark>
Línea que sigue\
en la siguiente
Cómo se escribe
[Servicios](/servicios)
[ir a Bloques de código](#bloques-de-código)
[documentación de Astro Starlight](https://starlight.astro.build/es/)
Texto con una nota.[^1]
[^1]: Contenido de la nota.

Tarjetas para mandar a otras páginas. Una suelta:

O varias en rejilla:

Y tarjetas con icono para agrupar ideas (no son enlaces):

Instalación

Qué hace falta antes de empezar.

Uso diario

Los comandos que más se repiten.

Cómo se escribe
<LinkCard title="Herramientas" href="/herramientas" description="Texto de la tarjeta." />
<CardGrid>
<LinkCard title="Técnicas" href="/tecnicas" description="..." />
<LinkCard title="Metodologías" href="/metodologias" description="..." />
</CardGrid>
<Card title="Instalación" icon="setting">Contenido.</Card>
  • Elemento de lista
  • Otro elemento
    • Elemento anidado (dos espacios delante)
    • Otro anidado
  1. Primer paso
  2. Segundo paso
  3. Tercer paso
  • Tarea hecha
  • Tarea pendiente

Las listas de tareas son checklists interactivas: se pueden marcar, el estado se guarda en tu navegador y debajo aparece el progreso con un botón para reiniciar. Lo que esté marcado con [x] en el texto empieza marcado. Es lo que usan las Metodologías para sus pasos.

Cómo se escribe
- Elemento
- Anidado
1. Primer paso
2. Segundo paso
- [x] Tarea hecha
- [ ] Tarea pendiente

Una cita o un fragmento copiado de la documentación oficial. Sirve para separar lo que dice la fuente de lo que explicas tú.

Cómo se escribe
> Texto citado.

Cuatro tipos, de menos a más importante.

Cómo se escribe
:::note
Texto del aviso.
:::
:::caution[Título personalizado]
Tipos: note, tip, caution, danger.
:::

Todos los bloques tienen botón de copiar (aparece al pasar el ratón). Se indica el lenguaje justo después de las tres comillas para colorear la sintaxis.

Con lenguaje de shell y un title, el bloque se dibuja como una ventana de terminal:

terminal
sudo apt update
rsync -az --delete dist/ usuario@servidor:/var/www/sitio/

Con otro lenguaje, el title se muestra como la pestaña del archivo:

/etc/nginx/conf.d/sitio.conf
server {
listen 80;
server_name ejemplo.com;
root /var/www/sitio;
}

Para salidas de comandos o texto plano, frame="none" quita la ventana:

Filesystem Size Used Avail Use% Mounted on
/dev/sda1 40G 12G 26G 32% /

Líneas marcadas {2}, añadidas ins={3}, quitadas del={4} y una palabra resaltada "root":

server {
listen 80;
listen 443 ssl;
server_name viejo.ejemplo.com;
root /var/www/sitio;
}

Con el lenguaje diff, las líneas que empiezan por + y - se colorean:

services:
web:
image: nginx:1.25
image: nginx:1.27

Con wrap, las líneas largas se parten en vez de obligar a hacer scroll lateral:

Ventana de terminal
docker run --rm -it --name prueba -p 8080:80 -v "$(pwd)/html:/usr/share/nginx/html:ro" -e TZ=Europe/Madrid nginx:alpine

Escribe los datos que cambian como {NOMBRE} (mayúsculas, números y _). Pulsa el botón { } de la cabecera o Alt + V, rellena los valores y se sustituyen en todos los comandos de la wiki, también en lo que copia el botón de copiar. Sin valor, el placeholder se ve resaltado; al hacer clic en uno se abre el panel en esa variable. Los valores se guardan solo en tu navegador.

terminal
ssh {USUARIO}@{SERVIDOR} -p {PUERTO}
rsync -az --delete dist/ {USUARIO}@{SERVIDOR}:{RUTA}
Cómo se escribe
```bash title="terminal"
comando
```
```nginx title="/etc/nginx/nginx.conf"
contenido del archivo
```
```txt frame="none"
salida sin marco
```
```nginx {2} ins={3} del={4} "root"
...
```
```diff lang="yaml"
-línea quitada
+línea añadida
```
```bash wrap
comando muy largo
```
```bash
ssh {USUARIO}@{SERVIDOR}
```
Opción Para qué sirve Por defecto
-a Copia en modo archivo no
-z Comprime durante la transferencia no
--delete Borra en destino lo que sobra no
Cómo se escribe
| Opción | Para qué sirve | Por defecto |
| :----- | :------------- | ----------: |
| `-a` | Copia en modo | no |

Para procedimientos numerados con bloques dentro:

  1. Instala las dependencias.

    Ventana de terminal
    npm ci
  2. Compila el sitio.

    Ventana de terminal
    npm run build
  3. Revisa el resultado en dist/.

Cómo se escribe
<Steps>
1. Primer paso.
```bash
comando
```
2. Segundo paso.
</Steps>

Útiles para el mismo comando en varios sistemas. Con syncKey, todas las pestañas con la misma clave cambian a la vez en toda la wiki.

Ventana de terminal
sudo systemctl restart nginx
Cómo se escribe
<Tabs syncKey="so">
<TabItem label="Linux">
```bash
comando para Linux
```
</TabItem>
<TabItem label="Windows">
```powershell
comando para Windows
```
</TabItem>
</Tabs>
  • Directorio/opt/docker-services/
    • Directorionginx-static/
      • docker-compose.yml
      • Directorioconfig/
        • nginx.conf el archivo importante
    • Directorioshards/
      • …
Cómo se escribe
<FileTree>
- carpeta/
- archivo.yml
- **destacado.conf** comentario
- …
</FileTree>

Etiquetas: Nota Consejo Precaución Peligro Éxito Por defecto

Iconos:

Botón principal Secundario
Cómo se escribe
<Badge text="Consejo" variant="tip" />
<Icon name="rocket" />
<LinkButton href="/servicios" icon="right-arrow">Texto</LinkButton>
<LinkButton href="/servicios" variant="secondary">Texto</LinkButton>
Salida completa del comando
Reading package lists... Done
Building dependency tree... Done
All packages are up to date.
Cómo se escribe
<details>
<summary>Título visible</summary>
Contenido que se despliega (deja una línea en blanco arriba y abajo).
</details>

Las imágenes van en la misma carpeta que la entrada (o en una subcarpeta) y se enlazan con ruta relativa. Astro las optimiza al compilar.

Cómo se escribe
![Texto alternativo que describe la imagen](./captura.png)

Una línea horizontal para cortar dentro de una sección:


Cómo se escribe
---

En .mdx se puede dejar texto que no se publica, por ejemplo notas para ti mismo. Esta página tiene uno justo después de los import.

Cómo se escribe
{/* Esto no aparece en la página. */}

Cuatro bloques que no se escriben en el texto: salen del frontmatter (o se calculan solos) y solo aparecen si tienen datos.

  • Ficha (arriba del todo): puertos, protocolo, documentación oficial y archivos de configuración. Pensada para Servicios, pero funciona en cualquier entrada.
  • Referencias (al final): enlaces externos, con el dominio a la vista.
  • Relacionado (al final): tarjetas a otras páginas de la wiki. Si una ruta no existe o es un borrador, se omite y avisa al compilar.
  • Mencionado en (al final): las páginas que enlazan a esta. No se escribe: se calcula al compilar a partir de los enlaces del texto. Esta guía enlaza a los cuatro pilares, así que en cada uno aparece «Mencionado en: Guía de recursos».
Cómo se escribe
ficha:
puertos: ['80/tcp', '443/tcp']
protocolo: HTTP / HTTPS
documentacion: https://nginx.org/en/docs/
archivosConfig: [/etc/nginx/nginx.conf]
referencias:
- titulo: Documentación oficial
url: https://ejemplo.com/docs
relacionado: [/servicios/nginx, /herramientas/rsync]

La cabecera entre --- de cada archivo. Solo title es obligatorio.

Frontmatter
---
title: Título de la entrada
description: Entradilla gris bajo el título.
draft: true # si está, no se publica (sí se ve en local)
tags: [docker, nginx] # etiquetas libres; sirven de filtro en el buscador
sidebar:
order: 1 # posición en el menú lateral
label: Nombre corto # texto en el menú, si quieres otro distinto del título
badge: Nuevo # etiqueta junto al nombre en el menú
relacionado: [/servicios/otra-entrada]
referencias:
- titulo: Documentación oficial
url: https://ejemplo.com/docs
ficha:
puertos: ['80/tcp', '443/tcp']
protocolo: HTTP
documentacion: https://ejemplo.com/docs
archivosConfig: [/etc/servicio/servicio.conf]
---
  1. Las notas al pie van numeradas y enlazan de vuelta al texto. ↩

Referencias

Relacionado