Blog

The official docs, now with search and in your language

With 0.8.3, the DiagramaHub documentation site finally looks right: navigation, search, dark mode, and English and Spanish. The app also drops its last untranslated labels.

If you ever opened the DiagramaHub documentation site and saw raw Markdown with no menu and no search, it wasn't your browser. GitHub Pages was publishing the docs/ folder with Jekyll's default theme, and the site root returned a 404. 0.8.3 fixes that and uses the opportunity to polish the app's language support.

A real documentation site

The docs live at diagramahub.github.io/diagramahub and are now built with MkDocs Material. Here's what you get:

  • Installation guide for hosting DiagramaHub on your own infrastructure with Docker Compose.
  • Release notes for every release, from 0.1.0 to the current one.
  • Search with suggestions and term highlighting.
  • Navigation with tabs, a back-to-top button and previous/next links.
  • Light and dark mode, following your system preference.
  • Copy button on every code block, handy for the install commands.

Truly in English and Spanish

The site has a language switcher that takes you to the same section in the other language. There was a catch: Material only supports one UI language for the whole site, so English pages showed the search box and table of contents in Spanish. A per-folder theme override solves it, and every page now uses the UI of its own language.

flowchart LR
    A[Push or pull request] --> B[GitHub Actions]
    B --> C{"mkdocs build --strict"}
    C -->|Broken link| D[Build fails, nothing is published]
    C -->|All good| E[GitHub Pages]
    E --> F["/es/ and /en/"]

The build also runs in strict mode on every push and pull request: a broken link fails the build instead of shipping a broken page.

The app, with no stray strings

0.8.3 also went over the editor UI. About 40 strings (tooltips, placeholders, screen reader labels and image alt text) were written straight into the components, so the English UI showed Spanish tooltips (and vice versa). They all go through the translations now, and an automated test checks that English and Spanish have the same keys.

Two more details:

  • Accessible icon-only buttons. Zoom, text size, fullscreen and close now have an aria-label, so screen readers announce them by name.
  • Page metadata that follows your language. The page's lang attribute, the tab title and the description change with the active language. The page used to declare itself English even though the default UI is Spanish.

If you self-host

0.8.3 has no migrations and no new features. Rebuild the images as usual:

docker compose up -d --build

If you maintain a fork with its own docs site, switch the GitHub Pages source from "Deploy from a branch" to "GitHub Actions".

Next step

Browse the documentation, install DiagramaHub with the installation guide, or try it without installing anything on DiagramaHub Cloud. Spotted something missing from the docs? Open an issue in the repository.