PageTop Website

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

[![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=License&style=for-the-badge)](#license)
## 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///`), 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///...` | 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.