pagetop-website/README.md
Manuel Cillero 4e007feec8 📝 Doc cron, mail queue, CSRF and flash messages
Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
2026-11-02 14:46:28 +01:00

6.4 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-cron, pagetop-htmx, pagetop-mail, pagetop-seaorm (with SQLite), pagetop-user, pagetop-build, serde, thiserror, tokio 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. Finally, environment variables named PAGETOP_<SECTION>__<KEY> override individual keys (e.g. PAGETOP_SERVER__BIND_PORT=80).

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.