Archivo de configuración
El archivo de configuración es opcional. Por defecto, htmlpress toma todos los
archivos .html de la carpeta que le indiques.
Htmlpress se configura con un único archivo en la raíz de tu proyecto:
htmlpress.yaml. Colócalo junto a tus páginas y htmlpress lo detecta automáticamente: sin flags ni
variables de entorno. Sus claves siguen la configuración de
Livemark.
Configuración mínima
Todas las claves son opcionales, así que un proyecto no necesita ninguna configuración. La más pequeña que resulta útil le da nombre al sitio:
title: My docs
Un htmlpress.yaml vacío equivale a no tenerlo. Sin él, cada archivo
.html y .md del proyecto (por defecto
include: ["**/*.html", "**/*.md"]) se convierte en una página,
renderizada con el layout y el tema integrados: barra lateral, tabla de contenidos,
modo oscuro, todo por defecto. Cualquier otro archivo se copia tal cual a la salida,
en la misma ruta. Las carpetas ocultas como .git/ y
.htmlpress/, y node_modules/, se omiten.
Qué puedes configurar
Cada clave tiene un valor predeterminado razonable. El conjunto completo:
| Clave | Predeterminado | Uso |
|---|---|---|
include |
**/*.html, **/*.md |
un glob o una lista: los archivos .html y .md que se
convierten en páginas; un .md junto a su gemelo
.html
se copia en su lugar
|
exclude |
ninguno | un glob o una lista: archivos que quedan totalmente fuera de la compilación, sean páginas o no |
title |
el nombre de la carpeta | la cabecera y el título de cada pestaña |
description |
ninguno | para las páginas que no tienen una propia |
site |
ninguno |
la URL pública, para los enlaces canónicos y sociales y
sitemap.xml
|
base |
ninguno |
la subruta bajo la que se sirve el sitio, como /repo/ en GitHub
Pages; consulta Ruta base
|
logo |
ninguno | la URL de una imagen, mostrada antes del título del sitio |
favicon |
el logo | la URL del icono del sitio |
banner |
ninguno | HTML para una barra de anuncios sobre la cabecera |
breadcrumbs |
true |
la ruta de carpetas sobre el contenido de cada página; el
<meta name="breadcrumbs"> de una página la anula
|
head |
ninguno |
meta, links y scripts añadidos al head
de cada página; consulta
Metadatos del sitio
|
links |
ninguno | enlaces en la cabecera o en la barra lateral; consulta Enlaces externos |
sections |
ninguno | partes del sitio con una navegación propia; consulta Secciones de artículos |
edit |
ninguno | un enlace "Editar esta página": esta URL seguida de la ruta de la página |
contentSignals |
todas true |
search, aiInput y aiTrain: cómo pueden
usar el contenido los sistemas automatizados, escrito en
robots.txt; consulta
Agentes de IA
|
codeThemeLight, codeThemeDark |
catppuccin-latte, catppuccin-mocha |
Los temas de los bloques de código; consulta Temas de sintaxis. |
patches |
ninguno |
Metadatos de página definidos desde la configuración, y archivos
.md publicados como páginas; consulta
Parches de artículos.
|
plugins |
ninguno |
Plugins de Textlane añadidos al pipeline de
páginas, cada uno un nombre o { name, options }:
md sobre el árbol de una página Markdown tras sus directivas,
html sobre el árbol de cada página antes de los ids de los
encabezados. Un plugin que htmlpress ya ejecuta, como md.gfm o
html.slug, se reconfigura con tus opciones en lugar de ejecutarse
dos veces; consulta Plugins.
|
skills |
ninguno |
un glob o una lista de archivos SKILL.md, relativos al proyecto,
para publicar como
skills de agente
|
languages |
uno, inglés | los idiomas en los que se publica el sitio, el predeterminado primero; consulta Traducciones |
Con languages, los textos que ve un lector (title,
description, banner y los títulos de enlaces y secciones)
también aceptan un mapa por código de idioma, como
title: { en: Docs, es: Guía }.
El esquema completo está en
rust/src/models/config.rs. Una clave desconocida es un error, así que una errata nunca pasa en silencio.
Include y exclude
include reemplaza el valor predeterminado, así que lista todas las
carpetas que quieras. Las carpetas de cada glob anteriores a su primer comodín son
su base: solo se leen los archivos bajo una base, y se sirven sin ella, de modo que
docs/**/*.html compila docs/guide.html en
/guide/. Los demás archivos bajo una base, incluidos los
.html que include deja fuera, se copian tal cual.
Los globs son relativos al proyecto y no pueden salir de él (.. o una
ruta absoluta es un error): * se queda dentro de una carpeta,
** atraviesa carpetas, y un patrón de include o
exclude que no coincide con ningún archivo muestra una advertencia.
Ruta base
Con base definido, cada URL relativa a la raíz de la compilación (en
href, src, srcset, poster y
action, tanto en las páginas como en el layout y en el HTML de la
configuración) la recibe como prefijo: escribe /guide/ y el sitio
enlaza a /repo/guide/. Las URL relativas y absolutas no se tocan, y
tampoco las url() del CSS propio de una página. start y
preview también sirven el sitio bajo la base, y redirigen
/ allí; reinicia start tras cambiar base.
Ejemplo completo
La mayoría de los sitios reales acaban pareciéndose a esto:
site: https://htmlpress.dev
title: Htmlpress
description: Static site generator
logo: /logo.svg
banner: 'Version 1 is out: <a href="/changelog/">read more</a>'
include: docs/**/*.html
exclude: docs/**/_*
links:
- title: GitHub
url: https://github.com/datisthq/htmlpress
- title: Chat
url: https://discord.gg/example
position: sidebar
head:
scripts:
- src: https://stats.example.com/script.js
defer: ""
contentSignals:
aiTrain: false
skills: .skills/*/SKILL.md
edit: https://github.com/datisthq/htmlpress/edit/main/docs/Adónde ir después
- Metadatos del sitio: título, descripción, favicon, logo.
- Secciones de artículos: divide el sitio en secciones con su propia navegación.
- Enlaces externos: enlaces de la cabecera y de la barra lateral.
- Temas de sintaxis: el aspecto de los bloques de código.
- Parches de artículos: sobrescribe los metadatos de una página desde la configuración.
- Sobrescritura/Escape: reemplaza cualquier layout, hoja de estilos o componente integrado.
- Rutas personalizadas: páginas con su propio layout.
Hecho con ❤ y Htmlpress