Guía Completa desde Cero: Cómo Crear y Desplegar tu propio Blog Accesible con Astro y Docker

En este tutorial aprenderás a crear, personalizar y publicar en internet tu propio blog web moderno, ultrarrápido y 100% accesible (optimizado para personas con discapacidad visual y usuarios de lectores de pantalla como NVDA, JAWS o TalkBack).

No necesitas tener conocimientos previos de programación ni experiencia previa. En esta guía explicaremos detalladamente qué es cada herramienta, para qué sirve, cómo descargarla e instalarla paso a paso en tu ordenador y cómo poner en marcha tu sitio web.

🛠️ 1. Glosario de Herramientas (Explicado para Principiantes)

Antes de empezar, conozcamos los bloques principales que utilizaremos para construir nuestro blog:

Astro: Es un generador de páginas web estáticas de última generación. Convierte el contenido que escribes en texto plano en archivos HTML ultraligeros que se cargan de forma instantánea en cualquier navegador.
Node.js y npm:
- Node.js: Es un programa gratuito que permite a tu ordenador ejecutar el motor que procesa y construye tu sitio web con Astro.
- npm (Node Package Manager): Es el gestor de paquetes de Node.js. Es una herramienta que descarga e instala automáticamente las librerías necesarias para que tu blog funcione.
Git: Es una herramienta gratuita de control de código que permite descargar la plantilla del blog a tu ordenador con un solo comando de consola.
Markdown (.md): Es una forma de escribir texto enriquecido (con títulos, negritas, listas y enlaces) de forma rápida y sencilla utilizando cualquier editor de notas, sin necesidad de programas complejos.
Docker y Docker Compose: Son herramientas de automatización. Permiten empaquetar aplicaciones web dentro de “cajas” o contenedores aislados en un servidor o servidor NAS para que se compilen y ejecuten de forma limpia.
Nginx: Es un servidor web de alto rendimiento encargardo de recibir a las visitas que entran a tu sitio web desde internet y entregarles las páginas HTML de tu blog de forma segura (con cifrado HTTPS).

💻 2. Paso a Paso: Instalación de Herramientas Básicas

A. Instalación de Node.js y npm

Node.js es indispensable para construir el blog.

🪟 En Windows:

Abre tu navegador web y entra a la página oficial: https://nodejs.org/.
Haz clic en el botón verde que dice LTS (Long Term Support) para descargar el instalador automático.
Ejecuta el archivo .msi descargado y sigue el asistente haciendo clic en Next (Siguiente) en todas las pantallas hasta completar la instalación.

🍏 En Mac:

Entra a https://nodejs.org/, descarga el instalador .pkg versión LTS y ejecútalo.

🐧 En Linux (Ubuntu / Debian):

Abre una terminal y ejecuta los siguientes comandos:

sudo apt update
sudo apt install -y nodejs npm

🔍 Verificación de Node.js:

Abre una ventana de consola (en Windows: pulsa Inicio, escribe cmd y pulsa Enter) y ejecuta los siguientes dos comandos:

node -v
npm -v

Si la consola responde mostrando un número de versión (por ejemplo v22.12.0 y 10.9.0), la instalación se ha realizado con éxito.

B. Instalación de Git

Git nos permitirá descargar la plantilla básica del blog (AstroPaper).

🪟 En Windows:

Entra en la página oficial de Git: https://git-scm.com/.
Haz clic en Download for Windows y ejecuta el instalador descargado.
Puedes dejar todas las opciones por defecto haciendo clic en Next hasta finalizar.

🍏 En Mac:

Abre la terminal de Mac y escribe:

xcode-select --install

🐧 En Linux (Ubuntu / Debian):

sudo apt install -y git

🔍 Verificación de Git:

En tu terminal de comandos, escribe:

git --version

Debe responder mostrando algo como git version 2.45.0.

📂 3. Descarga y Primer Arranque de tu Blog

Ahora que tenemos las herramientas preparadas, vamos a descargar la plantilla AstroPaper y ponerla a funcionar en nuestro ordenador.

Paso 1: Clonar o descargar el proyecto

Abre la terminal de comandos de tu ordenador y ejecuta el siguiente comando para descargar una copia limpia de la plantilla a una carpeta llamada mi-blog:

git clone https://github.com/satnaing/astro-paper.git mi-blog

Paso 2: Entrar a la carpeta del blog

cd mi-blog

Paso 3: Instalar las dependencias

Ejecuta el siguiente comando para que npm descargue automáticamente todos los paquetes que necesita el blog:

npm install

Paso 4: Iniciar el servidor local de prueba

Inicia el blog en modo de pruebas en tu propio ordenador:

npm run dev

La consola te mostrará una dirección local similar a esta:
http://localhost:4321/

Abre tu navegador de internet y entra a http://localhost:4321. ¡Felicidades! Ya tienes tu blog funcionando en tu ordenador.

⚙️ 4. Personalizar la Configuración (`astro-paper.config.ts`)

Dentro de la carpeta mi-blog, busca el archivo llamado astro-paper.config.ts. Ábrelo con un bloc de notas o con tu editor de texto favorito (como Visual Studio Code).

Aquí puedes personalizar los títulos y datos de tu blog:

export const SITE = {
  website: "https://midominio.com/", // La dirección web pública que tendrá tu blog
  author: "Tu Nombre",             // Tu nombre o pseudónimo
  profile: "https://midominio.com/sobre-mi",
  desc: "Blog personal sobre tecnología, proyectos y guías accesibles.",
  title: "Mi Blog Accesible",       // El nombre principal de tu sitio web
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,           // Permite cambiar entre modo claro y oscuro
  postPerIndex: 10,                 // Número de entradas en la portada
  postPerPage: 10,                  // Número de entradas por página
  scheduledPostMargin: 15 * 60 * 1000,
};

Guarda los cambios en el archivo. El servidor local actualizará la vista en tu navegador automáticamente.

✍️ 5. Cómo Escribir y Publicar tu Primer Artículo

Todas las publicaciones de tu blog se guardan en forma de archivos de texto con extensión .md (Markdown) dentro de la carpeta:
src/content/posts/

Crear una nueva entrada:

Crea un archivo nuevo dentro de src/content/posts/ llamado mi-primer-articulo.md.

En la parte superior de cada archivo Markdown debes incluir una cabecera de datos en formato YAML delimitada entre dos líneas de tres guiones (---):

---
author: Tu Nombre
pubDatetime: 2026-08-03T10:00:00Z
title: Mi Primer Artículo en el Blog
slug: mi-primer-articulo
featured: false
draft: false
tags:
  - tecnologia
  - proyectos
  - inicio
description: "Resumen breve de mi primera publicación en el blog para redes sociales y buscadores."
---

¡Bienvenidos a mi nuevo blog accesible! 🎉

Este es el contenido de mi primera entrada. Escribir en **Markdown** es muy sencillo:

### Encabezados de sección:
Para crear subtítulos usa almohadillas `#`:
- `# Título Principal` (h1)
- `## Sección Secundaria` (h2)
- `### Subsección` (h3)

### Formato de texto:
- Para **texto en negrita**, rodea las palabras con dos asteriscos: `**texto en negrita**`.
- Para *texto en cursiva*, rodea las palabras con un asterisco: `*texto en cursiva*`.

### Bloques de aviso destacados:
> 📌 **Nota:**  
> Esta es una nota informativa destacada.

> [!TIP]
> Un consejo útil para tus lectores.

Al guardar el archivo mi-primer-articulo.md, tu blog lo detectará de inmediato y creará la nueva página web.

🐳 6. Despliegue Automatizado con Docker en un Servidor o NAS

Si quieres publicar tu blog en internet en un servidor Linux o en un NAS (como Synology) para que se actualice solo sin tener que compilarlo a mano, puedes usar Docker.

¿Qué es Docker y por qué usarlo?

Docker crea una “caja virtual” en el servidor con todo lo necesario instalado. Así, no tienes que instalar Node.js ni configurar librerías manualmente en tu servidor.

Paso 1: Crear el archivo `docker-compose.yml`

En la carpeta donde tengas alojado tu proyecto en el servidor (por ejemplo /srv/mi-blog/), crea un archivo llamado docker-compose.yml:

version: '3.8'

services:
  astro-blog:
    container_name: mi-blog-builder
    image: node:22-alpine
    working_dir: /app
    volumes:
      - /srv/mi-blog/entradas_blog:/app/src/content/posts:rw
      - /srv/mi-blog/web_publica:/output:rw
      - /srv/mi-blog/codigo_fuente:/app:rw
    command: sh -c "npm install && node watcher.js"
    restart: unless-stopped

Paso 2: Script de Auto-publicación (`watcher.js`)

Crea un archivo llamado watcher.js en la raíz de tu proyecto. Este script revisará la carpeta de entradas cada 2 segundos y, si encuentra un archivo nuevo o modificado, compilará la web automáticamente:

import { spawn } from "child_process";
import fs from "fs";

const postsDir = "/app/src/content/posts";
const outDir = "/output";
let isBuilding = false;

function buildSite() {
  if (isBuilding) return;
  isBuilding = true;
  console.log("Detectado nuevo contenido. Compilando el blog...");

  const child = spawn("npx", ["astro", "build"], { stdio: "inherit" });

  child.on("close", (code) => {
    isBuilding = false;
    if (code === 0) {
      fs.cpSync("/app/dist", outDir, { recursive: true });
      console.log("¡Sitio web actualizado con éxito!");
    }
  });
}

setInterval(() => {
  if (fs.existsSync(postsDir)) {
    buildSite();
  }
}, 2000);

Paso 3: Arrancar el contenedor Docker

En la consola de tu servidor ejecuta:

docker-compose up -d

A partir de este momento, cualquier archivo .md que guardes en la carpeta entradas_blog se compilará y publicará solo en unos segundos.

🔒 7. Publicar en Internet con Nginx y Certificado HTTPS

Para que tus visitantes accedan a tu blog a través de un nombre de dominio (como https://midominio.com), utilizaremos Nginx como servidor web.

Configuración básica de Nginx (nginx.conf):

server {
    listen 443 ssl;
    server_name midominio.com;

    charset utf-8;

    ssl_certificate /etc/letsencrypt/live/midominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/midominio.com/privkey.pem;

    location / {
        root /srv/mi-blog/web_publica;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

♿ 8. Garantía de Accesibilidad Universal (WCAG 2.1 AA)

Tu nuevo blog incluye características avanzadas de accesibilidad:

Estructura semántica limpia: Encabezados correctos (h1, h2, h3) para que los lectores de pantalla puedan saltar entre secciones fácilmente.
Operatividad total con teclado: Cualquier usuario puede navegar por los menús y artículos usando solo la tecla Tabulador, Enter y las Flechas de dirección.
Contraste de alto rendimiento: Colores ajustados para facilitar la lectura a personas con baja visión o fatiga visual.

💡 Resumen de Buenas Prácticas

Guarda tus archivos Markdown: Mantén siempre una copia de seguridad de la carpeta donde escribes tus artículos (.md).
Usa texto alternativo en imágenes: Al añadir imágenes a tus artículos, incluye siempre una descripción clara:
![Descripción accesible de la imagen](ruta-de-la-imagen.jpg)
Disfruta redactando: Publicar en tu propio blog estático es rápido, seguro y totalmente independiente de plataformas de terceros.

Guía Completa desde Cero: Cómo Crear y Desplegar tu propio Blog Accesible con Astro y Docker

🛠️ 1. Glosario de Herramientas (Explicado para Principiantes)

💻 2. Paso a Paso: Instalación de Herramientas Básicas

A. Instalación de Node.js y npm

🪟 En Windows:

🍏 En Mac:

🐧 En Linux (Ubuntu / Debian):

🔍 Verificación de Node.js:

B. Instalación de Git

🪟 En Windows:

🍏 En Mac:

🐧 En Linux (Ubuntu / Debian):

🔍 Verificación de Git:

📂 3. Descarga y Primer Arranque de tu Blog

Paso 1: Clonar o descargar el proyecto

Paso 2: Entrar a la carpeta del blog

Paso 3: Instalar las dependencias

Paso 4: Iniciar el servidor local de prueba

⚙️ 4. Personalizar la Configuración (astro-paper.config.ts)

✍️ 5. Cómo Escribir y Publicar tu Primer Artículo

Crear una nueva entrada:

🐳 6. Despliegue Automatizado con Docker en un Servidor o NAS

¿Qué es Docker y por qué usarlo?

Paso 1: Crear el archivo docker-compose.yml

Paso 2: Script de Auto-publicación (watcher.js)

Paso 3: Arrancar el contenedor Docker

🔒 7. Publicar en Internet con Nginx y Certificado HTTPS

♿ 8. Garantía de Accesibilidad Universal (WCAG 2.1 AA)

💡 Resumen de Buenas Prácticas

⚙️ 4. Personalizar la Configuración (`astro-paper.config.ts`)

Paso 1: Crear el archivo `docker-compose.yml`

Paso 2: Script de Auto-publicación (`watcher.js`)