pagetop-website/README.md
Manuel Cillero 1a41a456d4 ✨ Serve the PageTop guides with pagetop-mdbook
Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.

Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.

Move the configuration to config/common.toml and translate the README
to English.
2026-10-17 08:06:02 +02:00

6.3 KiB

PageTop Website

Official website of PageTop, to introduce this development environment to the community.

License

Overview

Web application built with PageTop to present its own ecosystem to the community, available at pagetop.cillero.es. It is the entry point to the PageTop guides for developers and users.

The guides are mdBook books under doc/, one per version and language (doc/<version>/<language>/), all of them with the theme in doc/theme/. They are built and embedded into the binary when the application is compiled, and served as PageTop pages with pagetop-mdbook.

Requirements

  • Rust (edition 2024).
  • mdBook 0.4 on the PATH, to build the guides (cargo install mdbook --version "^0.4").
  • The pagetop and pagetop-mdbook repositories next to this one, as in the pagetop-projects workspace: the dependencies use relative paths.

Running

cargo run

The server listens on 0.0.0.0:8080 by default. Routes:

Route Content
/ PageTop welcome page
/doc/latest/{lang} Redirects to the latest guides (Spanish only, by now)
/doc/<version>/<lang>/... Chapters of the guides

The books are built into static/doc/ (not versioned) only when their sources change. The version that /doc/latest/{lang} points to, and the languages of the guides, are set in src/lib.rs (LATEST_DOC and DOC_LANGUAGES).

Checking the guides

The guides document the current PageTop code, so they must be checked again whenever PageTop changes. tools/doccheck.sh does it in one step:

tools/doccheck.sh                    # the latest Spanish guide (doc/v0.6/es)
tools/doccheck.sh doc/v0.7/es        # any other book

It needs mdbook and python3, and the pagetop repository next to this one. It runs three checks and ends with exit code 1 if any fails:

  1. Links. Builds the book and checks that every internal link points to an existing page and anchor.
  2. Examples. Extracts every ```rust block into tools/doccheck/examples/, removing the # prefix of the lines that mdBook hides, and compiles them against PageTop. Blocks not marked no_run are also executed, so their assert! are checked.
  3. Tests. Blocks with #[pagetop::test] become tests, and run with cargo test together with the fixed tests in tools/doccheck/tests/ (for example, localization.rs checks the translations of the localization chapter at run time).

How the guides are organized

Each book follows the four kinds of documentation of Diátaxis, one folder each:

Folder Kind Shape of a page
tutorials/ Learning by doing, in order Time, prerequisites and result; numbered steps that run; "what you built"; next steps
how-to/ One task A goal line; numbered steps; the complete example; how to check it; next steps
reference/ Looking things up Tables: options, components, attributes
explanation/ The why Prose and diagrams, few examples

Every page ends linking the next ones to read. The interactive (HTMX) pages end with a complete, runnable example. doccheck.sh compiles it, but what happens in the browser is only declared by its hx-* attributes: after changing one of them, run it and try it in a browser.

When writing a chapter:

  • Write the examples in English, whatever the language of the guide: identifiers, strings, comments, paths and configuration values. Translating a guide is then only translating its text. Use another language only where the example needs it (such as the Spanish values of an es-ES translation file).
  • Write every example as complete, compilable code. Hide the lines the reader does not need (imports, a wrapping function, helper stubs) with a leading # ; mdBook does not show them.
  • Use ```rust only for examples that can run with no server (with assert!), ```rust,no_run for the rest, and ```rust,ignore only for loose fragments that are not valid on their own.
  • Examples can use pagetop, pagetop-admin, pagetop-bootsier, pagetop-htmx, pagetop-seaorm (with SQLite), pagetop-user, pagetop-build, serde, thiserror and tower-http (with the compression-gzip, cors, limit and timeout features); the translations in tools/doccheck/src/locale/ (LOCALES_APP), and a static files bundle named app. If a chapter needs anything else, add it to tools/doccheck.
  • Examples and tests that start an application read tools/doccheck/config/: those with a database get a new in-memory SQLite one on every run.
  • Tests that share state (a static store, a database) run in the same process: write one test per flow, so that their results do not depend on the order they run in.

The first run compiles PageTop and takes a few minutes; the next ones only compile the examples.

Configuration

Settings are loaded in cascade from the config/ directory (or the one in the CONFIG_DIR environment variable): common.toml, then {run_mode}.toml according to PAGETOP_RUN_MODE (default by default), local.{run_mode}.toml and local.toml. The local files are not versioned. There are no environment variables that override individual keys.

Warning

PageTop is a personal project to learn Rust and its ecosystem. Its API is subject to frequent changes. Production use is not recommended, at least until version 1.0.0 is released.

License

The code is available under a dual license:

You may choose either license. This dual-license approach is the de facto standard in the Rust ecosystem.