Document pagetop-mail (configuration, templates, layout, previews, queue and tests with the outbox) and file uploads (`web::Upload`, `form::File`, `web::Download` and the [upload] settings). doccheck enables the mail queue, keeps mail in memory and saves uploads under `target/`. |
||
|---|---|---|
| config | ||
| doc | ||
| src | ||
| tools | ||
| .gitignore | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
| rustfmt.toml | ||
PageTop Website
Official website of PageTop, to introduce this development environment to the community.
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
pagetopandpagetop-mdbookrepositories next to this one, as in thepagetop-projectsworkspace: 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:
- Links. Builds the book and checks that every internal link points to an existing page and anchor.
- Examples. Extracts every
```rustblock intotools/doccheck/examples/, removing the#prefix of the lines that mdBook hides, and compiles them against PageTop. Blocks not markedno_runare also executed, so theirassert!are checked. - Tests. Blocks with
#[pagetop::test]become tests, and run withcargo testtogether with the fixed tests intools/doccheck/tests/(for example,localization.rschecks 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-EStranslation 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
```rustonly for examples that can run with no server (withassert!),```rust,no_runfor the rest, and```rust,ignoreonly for loose fragments that are not valid on their own. - Examples can use
pagetop,pagetop-admin,pagetop-bootsier,pagetop-cron,pagetop-htmx,pagetop-mail(with itsqueuefeature),pagetop-seaorm(with SQLite),pagetop-user,pagetop-build,serde,thiserror,tokioandtower-http(with thecompression-gzip,cors,limitandtimeoutfeatures); the translations intools/doccheck/src/locale/(LOCALES_APP), and a static files bundle namedapp. If a chapter needs anything else, add it totools/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, mail is kept in memory (pagetop_mail::outbox) and uploaded files go totools/doccheck/target/doccheck-uploads. - 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:
-
MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
-
Apache License, Version 2.0 (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.