GitHub Pages

Actualizado el 1 nov 2026

GitHub Pages sirve un directorio de archivos estáticos con una de dos formas de URL:

Sitio de usuario/organización: https://<user>.github.io/, servido desde un repositorio llamado <user>.github.io. Sin subruta.
Sitio de proyecto: https://<user>.github.io/<repo>/, servido desde cualquier otro repositorio. El prefijo /<repo>/ importa; las URLs de páginas y assets deben incluirlo.

Compila el sitio

htmlpress build

La salida queda en .htmlpress/build/.

Configura `base` para sitios de proyecto

Si publicas bajo https://<user>.github.io/<repo>/, define base para que cada URL relativa a la raíz de la compilación reciba el prefijo. Sigue escribiendo los enlaces sin él (/guides/build/); htmlpress lo añade. htmlpress start y preview sirven bajo la misma base, así que el desarrollo coincide con producción:

site: https://acme.github.io
base: /my-docs/

Para sitios de usuario/organización en la raíz, omite base por completo.

Los dominios personalizados se saltan la subruta /<repo>/ incluso en sitios de proyecto. Si vas a asociar un dominio como docs.example.com, deja base sin definir y define site con el dominio final.

Despliega manualmente

El despliegue puntual más sencillo usa el paquete gh-pages:

htmlpress build
npx gh-pages -d .htmlpress/build --nojekyll --dotfiles

Esto sube la compilación a la rama gh-pages. En la configuración de tu repositorio, define Pages → Source como "Deploy from a branch" y elige gh-pages / / (root).

Mantén --nojekyll: un despliegue desde rama ejecuta Jekyll, que descarta las carpetas que empiezan por _ y, con ellas, el tema en _htmlpress/. --dotfiles conserva .well-known/, donde viven las skills de agente.

Despliega con GitHub Actions

Las actions oficiales de Pages son el camino más limpio: sin rama adicional ni tokens de servicio.

name: deploy

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .htmlpress/build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Define Pages → Source como "GitHub Actions" en la configuración de tu repositorio.

Dominio personalizado

Añade al proyecto un archivo CNAME con tu dominio, junto a tus páginas:

docs.example.com

Todo archivo del proyecto que no sea una página se copia tal cual a la salida de compilación, en la misma ruta, así que un CNAME junto al index.html raíz acaba en la raíz de tu despliegue. Configura el DNS en tu registrador (un registro CNAME que apunte a <user>.github.io) y define el dominio en Pages → Custom domain.

Ver también

Metadatos del sitio: site es necesario para las URLs absolutas del sitemap y las etiquetas Open Graph.
Despliegue: volver al índice de hosts.

Hecho con ❤ y Htmlpress