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 main 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. Such a text can carry diagrams as well.
- A files folder — the page’s pictures and other files sit alongside, in their own folder. Pictures and documents shown right inside the text are taken from it too.
It looks roughly like this:
portal/ the portal root
├── document.json the home page description
├── {block}.md the home page block texts
├── comments.json comments on the home page (when there are any)
├── assets/ the home page pictures and files
└── news/
├── document.json
├── {block}_intro.md
└── comments.jsonWhy 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 service marks inside the description, and the agent updates them together with its edit. The portal itself never rewrites a page’s files: it reads them exactly as they lie on disk — so the version history shows precisely what the agent changed.
Comments on a page
Besides the description, the texts and the pictures, a page may carry one more file — the one with comments. These are the administrator’s remarks on a selected piece of the page’s text: a one-way queue of requests that the agent works through right at the page and answers in the chat. Such a file appears only when there are comments, and it disappears together with the last remark. The remarks are visible to administrators inside the portal only (see the Page Comments section).
Pictures and files in the text
A file from the page’s folder can be put right into the text — not as a separate block, but inside a paragraph or a list:
- A picture — a diagram, a table, a photo — appears in the text in its place, with no extra clicks.
- Another file — a contract, an export, a presentation — is downloaded by the link without taking the reader off the page.
Everything else in the text stays as written: links to other sites, anchors inside the page, links to other portal pages and examples inside code blocks are left untouched. This works on the public site too: a visitor sees the same picture and downloads the same file.
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; where live numbers come from — in the Data Sources & Visualisations section; how one page serves many addresses — in Templates & Variables; what the agent controls — in Agent Management.