What it does
A smartbook is a course book written in Markdown with numbered formulas, exercises, exam questions, Python snippets and graphs, packed into a .ptsb file. Smart Builder writes them, and this reader shows them in the browser.
Read chapters. Formulas render with KaTeX and carry numbers like a printed book. Hovering a reference such as (2.1) shows the formula without leaving the page.
Study from the formula sheet. It collects every numbered formula from the chapters. Exercises and past exam questions come with hints and step-by-step solutions.
Run code and plot. The lab runs Python in the browser through Pyodide, with numpy and matplotlib, and MATLAB scripts through numbl, a MATLAB-compatible interpreter. Graphs are computed on the device. Neither sends code to a server.
Print. Chapters, the formula sheet, exercises and exams each have a print preview, with hints and solutions shown.
Import a book. Drop a .ptsb file on the home page. It stays in that browser and isn't uploaded anywhere.
The interface is in Italian, with light and dark themes. This repository ships only the example book ("Guida di esempio"). The public copy at politost.it/reader also lists the free books from politost-books.
Start
You need Node.js 22.22.2 or newer on the 22 line, or 24.15 or newer. CI uses 24.
git clone https://github.com/SuperTost100/politost-smartbook.git
cd politost-smartbook
npm ci # also copies the Pyodide runtime into public/pyodide/
npm run dev # opens on http://localhost:5173
Choose "Guida di esempio" to open the example book.
The default build needs no backend, account or database. npm run build writes a static site to dist/, which you can host anywhere with an SPA fallback. Self-hosting has the details.
Your data
Everything the reader keeps lives in your browser, under the site's origin:
- Imported books. Uploaded
.ptsb files and the copies of catalog books you opened are in the IndexedDB database politost-smartbook.
- Preferences. The theme, the last chapter and paragraph read in each book, and the 14-day snooze of the phone install banner are in localStorage (
politost-theme, politost-last-read, pwa-install-snooze-until).
- App shell. Production builds cache the app's own files in the Cache Storage entry
smartbook-static-v4.
There is no export. To back up an imported book, keep its .ptsb file and import it again when you need it. "Rimuovi da questo dispositivo" on an imported book's card deletes the book and its reading position. To clear everything, including catalog copies, delete the site's data in your browser settings.
Importing a book, running code in the lab and plotting graphs send nothing anywhere. The Pyodide runtime is served from the app's own origin. These are the actions that do talk to a server:
- Opening the library on a build with
VITE_BOOKS_URL. The reader fetches catalog.json from that site. politost.it points it at books.politost.it, and a build without it makes no such request.
- Opening a catalog book. The reader downloads its
.ptsb from the same site once, checks its size and sha256, and keeps a copy in IndexedDB. Later visits open it from that copy, offline.
- Using the platform (
VITE_PLATFORM_ENABLED=true). Sign-in, registration, terms consent, license keys, book access checks and the opening of a licensed chapter go to the API at VITE_API_URL. It is off by default and the public reader doesn't use it.
The public reader has no analytics or telemetry.
Configuration
All settings are optional. Set them in the environment or copy .env.example to .env.local:
| Variable | Default | What it does |
|---|
VITE_BASE_PATH | / | Serves the app from a subfolder, such as /reader |
VITE_BOOKS_URL | empty | Books site with a catalog.json. The home page lists its books |
VITE_PLATFORM_ENABLED | false | Turns on sign-in, licenses and cloud books |
VITE_API_URL | empty | Platform API address, required when the platform is on |
All four are read at build time. The platform API and its course books live in a separate private repository.
Checks
npm run lint
npm run test:content # content-core parser tests plus the reader's content tests
npm run test:unit
npm run build
npm run test:e2e # installs Playwright's Chromium on first run
CI runs all five on every pull request and on main. Auth tests run only with VITE_PLATFORM_ENABLED=true.
Search engines
The app renders in the browser, so a crawler that doesn't run JavaScript would see an empty page. On politost.it the Worker in deploy/politost/worker.js fixes that. For the library, each chapter, the formulario, the exercises and the exams, it sends the app's index.html with the page already in it: title, description, canonical, JSON-LD and the text. politost-books renders that text at build time and publishes it under books.politost.it/pages/, so a merged book change shows up without a reader deploy. In the browser the app replaces it with its own view.
Path under /reader | What the Worker sends |
|---|
/ | The library, with every published book and its chapters |
/libro/<id> | A 301 to the first chapter |
/libro/<id>/capitolo/<chapter>, formulario, esercizi, esami | The page, ready to index. A chapter also answers Accept: text/markdown with its Markdown |
/libro/<id>/laboratorio, grafici, stampa/... | The app with noindex |
/libro/<id> for a book that isn't published, such as an upload | The app with noindex |
/sitemap.xml | Every indexable page, built from the catalog |
| Any other unknown path | The app with status 404 |
When books.politost.it doesn't answer, the Worker sends the plain app, which loads its books the usual way.
Documentation
Related repositories
- politost-content: the content format spec, content-core (the parser, validator and PTSB reader bundled in
packages/content-core/, MIT) and ptsb-pack (Python CLI that packs books into .ptsb files).
- Smart Builder: turns lecture notes, textbooks and past exams into a smartbook. AGPL-3.0.
- Pyxis: a desktop study tutor that also opens
.ptsb files.
The archived politost-builder is withdrawn. Don't copy code from it.
License
AGPL-3.0. The bundled content-core package has its own MIT license. Books you open with the reader are not covered by this license.
