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

133 lines
6.3 KiB
Markdown

<div align="center">
<h1>PageTop Website</h1>
<p>Official website of <strong>PageTop</strong>, to introduce this development environment to the community.</p>
[![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=License&style=for-the-badge)](#license)
</div>
## Overview
Web application built with [PageTop](https://docs.rs/pagetop) to present its own ecosystem to the
community, available at [pagetop.cillero.es](https://pagetop.cillero.es). It is the entry point to
the PageTop guides for developers and users.
The guides are [mdBook](https://rust-lang.github.io/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](https://git.cillero.es/manuelcillero/pagetop-mdbook).
## Requirements
- Rust (edition 2024).
- [mdBook](https://rust-lang.github.io/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
```sh
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:
```sh
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](https://diataxis.fr), 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](https://www.rust-lang.org/) 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:
* **MIT License**
([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
* **Apache License, Version 2.0**
([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
You may choose either license. This dual-license approach is the de facto standard in the Rust
ecosystem.