Guidedog / Documentación 0.2.0

Plantillas¶

La plantilla controla la presentación sin duplicar el contenido. Guidedog usa Jinja para HTML y Typst para PDF.

Las plantillas de Guidedog son archivos del proyecto, visibles y editables. guidedog quickstart coloca las plantillas que se usarán directamente en el proyecto:

_templates/layout.html define la estructura HTML mediante Jinja.
_templates/book.typ define el diseño, la tipografía y la cubierta del PDF mediante Typst.
_static/guidedog.css y _static/guidedog.js aportan los estilos y las funciones del navegador.

Las plantillas están en el proyecto, no ocultas en paquetes o cachés. Edítelas, recompile con guidedog build y compruebe el resultado con guidedog serve.

Plantillas HTML¶

Guidedog renderiza layout.html con su motor Jinja integrado. Puede dividir el diseño en plantillas parciales, bibliotecas de macros y varios niveles de herencia.

Estructura modular de plantillas¶

Las plantillas pueden repartirse en archivos y subdirectorios de templates_path, cuyo valor predeterminado es ["_templates"]:

my-docs/
├── conf.toml
├── index.rst
└── _templates/
    ├── layout.html
    ├── base.html
    ├── partials/
    │   ├── header.html
    │   ├── navigation.html
    │   ├── searchbox.html
    │   └── footer.html
    └── macros/
        └── components.html

Guidedog recorre los archivos y subdirectorios de templates_path. Las inclusiones e importaciones usan rutas relativas a esos directorios:

Listado 1 _templates/layout.html¶

{% extends "base.html" %}

{% block header %}
  {% include "partials/header.html" %}
{% endblock %}

{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

También puede definir macros Jinja en archivos separados e importarlas donde hagan falta:

Listado 2 _templates/macros/components.html¶

{% macro badge(label, type="info") %}
  <span class="badge badge-{{ type }}">{{ label }}</span>
{% endmacro %}

Listado 3 Usar macros en las plantillas¶

{% import "macros/components.html" as ui %}
{{ ui.badge("New", type="success") }}

Herencia del tema con `!layout.html`¶

Para modificar solo algunas partes del tema, herede el diseño integrado con la sintaxis de exclamación de Sphinx:

Listado 4 _templates/layout.html¶

{# Inherit Guidedog's built-in layout #}
{% extends "!layout.html" %}

{# Inject custom metadata or web fonts into the document head #}
{% block extrahead %}
  {{ super() }}
  <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}">
{% endblock %}

{# Replace or extend the footer with custom content #}
{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

{% extends "!layout.html" %} o {% extends "basic/layout.html" %} carga la plantilla del tema y evita volver a cargar recursivamente _templates/layout.html del proyecto.

En un bloque sobrescrito, {{ super() }} conserva el contenido del padre y permite añadir contenido antes o después.

Bloques del diseño¶

El layout.html integrado define bloques compatibles con las convenciones de Sphinx:

Bloque	Función
`doctype`	Declaración de tipo de documento; por defecto, `<!DOCTYPE html>`.
`htmltitle`	Elemento `<title>` dentro de `<head>`.
`linktags`	Enlaces de navegación y metadatos: `favicon`, `index`, `search`, `prev` y `next`.
`css`	Enlaces a hojas de estilo y variables CSS en línea.
`scripts`	Etiquetas JavaScript para búsqueda y funciones interactivas.
`extrahead`	Punto de inserción al final de `<head>` para fuentes, analítica o metadatos.
`header`	Cabecera anterior a la barra de navegación principal.
`relbar1`	Barra superior con marca, versión, búsqueda y selector de tema.
`rootrellink`	Punto de inserción antes de los enlaces relacionados.
`relbaritems`	Elementos personalizados de la barra de navegación.
`sidebar1`	Contenedor de la barra lateral izquierda.
`sidebartoc`	Árbol de navegación del índice dentro de `sidebar1`.
`breadcrumbs`	Ruta jerárquica de navegación sobre el artículo.
`document`	Contenedor del cuerpo del artículo.
`body`	Contenido HTML del documento actual: `{{ body }}`.
`relbar2`	Navegación inferior a los capítulos anterior y siguiente.
`footer`	Pie de página con derechos de autor, fecha de actualización y enlaces al código fuente.
`sidebar2`	Columna derecha con el índice de la página.

Buscar plantillas¶

Guidedog busca en el orden de templates_path de conf.toml y después en las plantillas internas. Los nombres son relativos a esos directorios; .. no permite salir de ellos.

Todo archivo o subdirectorio de templates_path es una dependencia. guidedog build y guidedog serve detectan adiciones, cambios y eliminaciones y vuelven a renderizar el sitio.

Variables de página¶

Guidedog usa los nombres de variables de Sphinx cuando existen, lo que permite reutilizar partes de sus temas.

Variable	Valor
`body`	El documento en HTML.
`title`	El título del documento.
`pagename`, `docname`	Nombre del documento, como `usage/install`. En páginas sin documento, `docname` está vacío y `pagename` contiene el nombre, como en Sphinx: `genindex`, `py-modindex`, `search` o una página creada desde una plantilla.
`toc`	La navegación creada a partir de las toctrees, en HTML.
`outline`	Las secciones del propio documento en HTML; vacío si no tiene secciones.
`prev`, `next`	Las páginas vecinas en orden de lectura, con `url` (también `link`) y `title`; ninguna en los extremos.
`project`, `version`, `release`, `copyright`, `language`	Las opciones del mismo nombre.
`html_title`, `docstitle`	`html_title`, por defecto «<project> <release> documentation».
`html_short_title`, `shorttitle`	`html_short_title`.
`root_doc`, `master_doc`	El nombre del documento raíz.
`pathto_root`	La ruta de la página a la raíz del sitio, como `../`.
`root_url`, `search_url`, `genindex_url`	Enlaces a la página raíz, la búsqueda y el índice general.
`css_files`, `js_files`	Listas de archivos con `url`: primero los propios de Guidedog, después `html_css_files` y `html_js_files`.
`logo_url`, `favicon_url`	`html_logo` y `html_favicon` dentro de `_static`; vacíos si no se configuran.
`accent`	`html_theme_options.accent`, el color del tema.
`sourcelink_url`	La fuente del documento bajo `_sources` cuando se muestra; vacío en caso contrario.
`last_updated`	La fecha de compilación en formato `html_last_updated_fmt` si se configura; vacío en caso contrario.
`show_copyright`, `show_sphinx`, `show_guidedog`, `has_source`, `show_source`	Las opciones `html_show_*` y `html_copy_source`.
`builder`, `file_suffix`	El nombre del generador, como `html`, y el sufijo de página.
Cada clave de `html_context`	El valor conserva su tipo, como en Sphinx: `false` es falso en `{% if %}`, los números son números, los arrays listas y las tablas diccionarios con el orden de `conf.toml`. `guidedog migrate` conserva las entradas literales de `html_context`; los valores calculados de `conf.py` quedan indefinidos y se leen como falsos.

pathto es la función de Sphinx: pathto("usage/install") da la URL del documento y pathto("_static/logo.svg", 1) la de un archivo del sitio, relativas a la página actual. En singlehtml el documento es una sección: la primera llamada da #document-usage-install allí y index.html#document-usage-install desde índice y búsqueda. Los nombres sin documento, como genindex o páginas de plantilla, son páginas raíz con cualquier constructor.

Páginas creadas con plantillas¶

html_additional_pages crea páginas solo con una plantilla, como Sphinx. Cada clave es un nombre de página y cada valor una plantilla de templates_path:

Listado 5 conf.toml¶

root_doc = "contents"

[html_additional_pages]
index = "indexcontent.html"
download = "download.html"

La plantilla suele extender layout.html y rellenar sus bloques para mantener el diseño común:

Listado 6 _templates/indexcontent.html¶

{% extends "layout.html" %}
{% block htmltitle %}<title>{{ shorttitle }}</title>{% endblock %}
{% block body %}
  <h1>{{ docstitle|e }}</h1>
  <p><a href="{{ pathto("tutorial/index") }}">Tutorial</a></p>
{% endblock %}

Recibe las variables de una página sin documento: pagename es su nombre (index), title y body están vacíos; pathto, toc, toctree() y html_context funcionan normalmente. html, dirhtml y singlehtml la escriben en la raíz como <name>.html (html_file_suffix) en cada construcción. Cambiar cualquier archivo de templates_path reconstruye todas las páginas.

Ubicación de la página y diferencias con Sphinx:

Una página con nombre de documento lo sustituye, como en Sphinx al escribirse al final. index = "landing.html" convierte index.html en portada, mientras index.rst sigue aportando el índice. Con singlehtml se conserva la página única y se omite la de plantilla con una advertencia.
dirhtml escribe download.html junto a genindex.html y search.html, donde Sphinx escribe download/index.html. pathto("download") devuelve ese archivo.
El nombre debe ser un archivo raíz. Se rechaza "sub/page" con build.additional_page porque los enlaces parten de la raíz. También se rechazan nombres ocupados, como genindex, donde Sphinx sobrescribiría una de las páginas.
guidedog migrate transfiere html_additional_pages de conf.py.

Errores¶

Un error de plantilla detiene la compilación e indica archivo, línea, texto y sugerencia:

TEMPLATE ERROR                                                  template.error

  _templates/base.html:1

No filter named 'defualt'.

Did you mean the filter 'default'?

Una variable no definida se muestra como vacío, igual que en Jinja.

Las plantillas descontroladas se detienen con error, sin bloquearse: sintaxis de más de 100 niveles (paréntesis, etiquetas y cadenas de operadores, filtros o elif), macros, inclusiones y bucles recursivos de más de 200, o recursión que exija más de 512 KiB de pila. Una lista que se contiene muestra [...], como Python.

Plantillas PDF¶

Typst compone el PDF. _templates/book.typ es un archivo normal que define la función book. Guidedog escribe la fuente así:

#import "/_templates/book.typ": book
#show: book.with(title: ..., author: ..., version: ..., date: ...,
  lang: ..., paper: ..., numbering: ..., logo: ...)
// the chapters, one per document of the root toctree

Todo lo que decide el aspecto del libro está en ese archivo: fuentes, tamaño y márgenes, títulos, portada, cabeceras e índice.

Parámetros¶

Parámetro	Valor
`title`	El `title` del libro en `pdf_documents` o, en su defecto, `project`.
`author`	El `author` del libro o, en su defecto, la opción `author`.
`version`	`release`.
`date`	`\|today\|`: `today` si se configura; de lo contrario, la fecha de compilación en formato `today_fmt`.
`lang`	`language`.
`paper`	`"a4"` o `"us-letter"` si `pdf_paper_size` es `letter`.
`numbering`	`true` cuando una toctree tiene la opción `numbered`.
`logo`	La ruta de `pdf_logo`; ausente si no se configura.
`copyright`	`copyright` para el colofón; solo se pasa a una plantilla que lo acepta.
`body`	Los capítulos.

La plantilla puede añadir parámetros con valores predeterminados. La de quickstart incluye accent, fuentes serif, sans y mono, size y page-ref. Este último añade el número de página a referencias si recibe una función como n => [p. #n].

Plantillas Typst modulares¶

Puede repartir estilos, macros y cubiertas en archivos .typ de _templates/ y combinarlos con #import y #include:

Listado 7 _templates/book.typ¶

#import "cover.typ": title-page
#import "typography.typ": apply-styles

#let book(
  title: "",
  author: "",
  version: "",
  date: "",
  lang: "en",
  paper: "a4",
  numbering: false,
  logo: none,
  body,
) = {
  apply-styles()
  title-page(title: title, author: author, version: version, logo: logo)
  body
}

Qué puede usar una plantilla¶

Paquetes de Typst

Funcionan paquetes como #import "@preview/cetz:0.4.2", descargados al primer uso. Con pdf_packages = "offline" se usan solo los ya presentes en disco.

Fuentes

Se pueden usar fuentes del sistema, como con typst. Añade carpetas mediante pdf_font_paths o usa pdf_fonts = "embedded" para limitarse a las fuentes integradas y obtener libros reproducibles byte a byte.

Preámbulo

pdf_preamble nombra un archivo Typst que sigue a #show: book, útil para unas pocas reglas set y show sin crear una plantilla propia.

Typst en un documento

Los documentos son reStructuredText y Markdown, no archivos Typst. Para incluir marcado Typst en el libro, escríbelo en un bloque raw, omitido en la web:

.. raw:: typst

   #align(center)[#text(size: 14pt)[Only in the book]]

.. only:: pdf limita también el contenido normal al libro.

Los errores de Typst indican archivo y línea, de la plantilla o del libro generado. Cada PDF tiene su fuente en _build/pdf/sources/<pdf-filename>.typ: reference-en.pdf usa sources/reference-en.pdf.typ. Un libro único conserva también _build/pdf/book-<language>.typ para inspección. Un fallo no publica; deja la fuente en la ruta indicada bajo _build/.doctrees/failed. Varios libros conservan fuentes de fallo distintas.

Escribir una plantilla nueva¶

Empiece por las copias de quickstart, que muestran todas las partes en uso:

Conserve el marcado de layout.html que espera la hoja de estilo predeterminada, o sustituya también _static/guidedog.css.
Mueva las partes repetidas a archivos e inclúyalas con include, o cree base.html y use extends desde layout.html.
Para el libro, cambie las reglas de book o escriba una función nueva con el mismo nombre y parámetros.

Use guidedog serve al editar. Guarde y recargue el navegador; el servidor reconstruye las entradas modificadas antes de servir la página.