Document Format

A page in the portal is not a database record but a folder with files. Inside live the page description and its texts. This format is deliberate: files can be kept in a version store, read easily and moved around, and they do not depend on a particular server.

A page is a folder

Every page has its own folder. Inside there are three kinds of content:

• The description file — everything about the page is written here: the title, the description, the icon, which blocks it consists of, its access and settings.
• Text files — large block texts are moved out of the description into separate files. That keeps the description short and surveyable, and the edits in the version history readable.
• The pictures folder — the page’s images sit alongside, in their own folder.

It looks roughly like this:

portal/                          the portal root
├── document.json                 the home page description
├── {block}.md                    the home page block texts
├── assets/                       the home page pictures
└── news/
    ├── document.json
    └── {block}_intro.md

Why exactly this way

Keeping content as plain files gives three benefits. First — a clean version history: every save rewrites the description whole, so the history shows exactly what changed, not hundreds of lines of accidental shuffling. Second — portability: the portal folder can be copied to another server and opened there with no export or import. Third — independence: if tomorrow you decide to move to another server or another brand, the content stays with you.

What sits in the page description

• Title — the page’s name, also shown in the tree. A required field.
• Description and icon — a short explanatory line under the title and the page’s little icon in the tree.
• Blocks — what the page is assembled from, in order. It can be an empty list while the page is still only an idea.
• Variables — the declared variables of sample pages (see Templates & Variables).
• Access — who can open the page: administrators only, staff after signing in, or everyone (see Page Access).
• Settings — the page width, menu participation, the agent’s recommendation, and the site’s own settings: its name, icon and menu depth.

What the server maintains itself

Creation time, last-modified time and the page’s version number are stamped by the server itself on every save. There is no need to edit them — and no point: the next save would overwrite them anyway.

Page addresses

A page’s address is its path through the folders from the portal root. Names are written in lowercase Latin letters with hyphens, for example press-releases. A special case is a folder named in square brackets, for example [tag]: that is a sample serving many addresses at once. Details are in the Templates & Variables section.

Substituting values

When a page is read, the server substitutes variable values into all of its strings: the page title, description, block headings, button labels and link addresses. Block texts are substituted in the browser instead — so a sample instantly shows the right variant when you navigate to an address.

What the content does not include

The portal content lives in its own repository folder, while the service data stays aside from it, in the /apps/portal volume. The Python environment (the set of programs the scripts compute with), the working folder for script files and the unread-page marks are all the server’s service data. They are not part of the version history, and when the content folder is copied to another server they are created anew.

Next: how a page is assembled from blocks — in the Blocks section; how one page serves many addresses — in Templates & Variables; what the agent controls — in Agent Management.

← Back to the documentation index