# GitHub Pages

> Despliega tu sitio en GitHub Pages, incluidos los sitios de proyecto bajo una subruta.

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

```sh
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:

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

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

> **Consejo**
>
> 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`](https://www.npmjs.com/package/gh-pages):

```sh
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)`.

> **Warning**
>
> 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.

```yaml
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](/es/customization/site-metadata/): `site` es necesario para las URLs absolutas del sitemap y las etiquetas Open Graph.
- [Despliegue](/es/deployment/): volver al índice de hosts.