How ForgeCMS Thinks
Before we rent a server and build your site, it helps to know how ForgeCMS thinks. You will not type most of the files yourself. The AI will. But when you know where things live, you can check its work, fix a typo in the browser, and ask for exactly what you want.
This chapter has no exercises. Read it once, and come back to it whenever you wonder "where does this live again?".
Goal
By the end of this chapter you will know:
- the four pieces of a ForgeCMS site and where each one lives,
- what a page looks like inside,
- what happens when somebody opens your website,
- why a typo never takes your site down.
Four pieces instead of one big system
A WordPress site is one big system: program, database, theme and plugins, all mixed together on one server. ForgeCMS splits a website into four simple pieces:
| Piece | What it is | Where it lives |
|---|---|---|
| Texts | Your words, as Markdown files | Codeberg |
| Pages | Which texts, pictures and elements a page shows, as small SML files | Codeberg |
| Configuration | Name, domain, languages, modules, the one file the server trusts | On your server (app.sml) |
| ForgeCMS | The program that turns all of this into web pages | On your server |
The important line runs between the first two and the last two. Texts and pages are things you change often, so they live on Codeberg, where you can edit them in the browser and every change is saved. Configuration and the program change rarely and decide what your site is allowed to do, so they stay on your server, where only you and your AI assistant can reach them.
Texts: Markdown
Your texts are written in Markdown, a way of writing plain text with a few marks for headings, bold words and links. You have probably seen it in chat apps already:
## Fresh bread, every morning
We are a family bakery in Wittenberg. Our sourdough is made
from a **twelve-year-old** starter.
- Tuesday to Saturday, 7:00 to 13:00
- [Write to us](/contact)
## makes a heading, **…** makes bold text, - starts a list, and [text](address) makes a link. That is almost everything you will ever need. A Markdown file is just text. You can open it on any computer in twenty years, and it will still be readable.
Pages: SML
A page says what is on it: a heading here, a text there, a picture, a contact form. ForgeCMS describes pages in SML (Simple Markup Language). It looks like this:
Page {
title: "Our Bakery"
Hero {
heading: "Fresh bread, every morning"
image: "/static/images/oven.jpg"
}
Markdown { src: "bakery.md" }
Cards {
Card { title: "Sourdough" text: "Baked daily from a twelve-year-old starter." }
Card { title: "Opening hours" text: "Tuesday to Saturday, 7:00 to 13:00" }
}
ContactForm { }
}
Read it from top to bottom, and you can almost see the page: a big picture with a heading, the text from bakery.md, two cards, and a contact form at the end. Every element has a name (Hero, Cards, ContactForm) and a few properties in the form name: "value". Curly braces { } show what belongs together.
You do not have to learn SML. It was designed so that an AI writes it correctly on the first try, and so that a human can read it at a glance. If the AI writes Card { title: "Opening hours" … } and the hours are wrong, you will see it immediately.
Text in Markdown, layout in SML. Keep this rule in mind. Markdown files should stay plain text, without HTML or design tricks. Buttons, price boxes, galleries and forms belong in the SML page. When you ask the AI for "a nice box with our prices", it will add an element to the page, not paste code into your text.
Configuration: app.sml
Every site has one file on the server called app.sml. It says:
- the name and the address of your site,
- which languages it speaks,
- where on Codeberg its texts and pages are,
- which modules are switched on, and how they are set up: who gets the mails from the contact form, which wallet receives payments, who may write newsletters.
app.sml is the one file the server trusts. Everything that has to do with money, mail or rights is set here, never in the texts on Codeberg. If somebody ever got into your Codeberg account, they could change your texts, but they could not redirect your payments or send mail in your name. Keep this in mind when you ask the AI for changes: "change the opening hours" is a text change on Codeberg, "send contact mails to my new address" is a change in app.sml on the server.
Menu and footer can live in either place. Many sites keep them in a file site.sml on Codeberg, so that adding a page to the menu is as easy as editing a text. We will set this up in Part II.
What happens when somebody opens your site
Say a visitor opens https://mybakery.com/about. In the fraction of a second before the page appears, ForgeCMS:
- looks up in its configuration which page belongs to
/about, - reads that page's SML file and the Markdown texts it uses,
- asks Codeberg whether any of these files have changed since last time,
- turns everything into a web page and sends it to the visitor.
The third step is the clever one. ForgeCMS keeps a copy of every file it has seen. It does not download your texts again for every visitor, it only asks Codeberg "anything new?". If the answer is no, it uses its copy. If you changed a text, it fetches the new version. That is why your changes appear on the live site within a few minutes, without anybody pressing "publish" and without restarting anything.
There is no database in this picture, and no program code from strangers running on your pages. That is why ForgeCMS is fast on the smallest server and why there is so little to attack.
Why a typo never breaks your site
Because ForgeCMS keeps a copy of everything, two things cannot take your site down:
- Codeberg is slow or down. ForgeCMS keeps showing the last copy it has.
- You made a mistake in a file, such as a missing
}in an SML page. ForgeCMS cannot read the new version, so it keeps showing the last working one and writes a warning to its log.
If you change something and it does not appear on the live site after a few minutes, the most likely reason is a small typo. Look for a missing quote " or a missing }, or ask the AI: "My last change does not show up on the site. Please find out why."
And because Codeberg saves every change, you can always go back. Every edit is a small step in the history of your site, with the date and a short note. "Undo my change from this morning" is a normal request.
Languages
ForgeCMS speaks as many languages as you like. The texts for your main language sit in your site's folder, and each other language gets its own subfolder, such as en/ for English. A page that has no translation yet simply shows the main language.
Visitors get the language their browser asks for. A small switcher in the menu lets them change it, and ForgeCMS remembers their choice. In Part II we will make a site in two languages.
Modules instead of plugins
In WordPress, every feature is a plugin from a different author. In ForgeCMS, the common features are modules, written and tested together with the rest of the system:
| Module | What it does |
|---|---|
| Blog | Posts with photos and videos, sections, search, a feed for readers |
| Contact form | Your own fields, messages arrive by mail, simple protection against spam |
| Newsletter | Sign-up with confirmation, mailings written like a text, unsubscribe link |
| Events | Dates with flyers, a page per event, calendar files for visitors |
| Feature requests | Visitors propose ideas and vote, one vote per person |
| Shop | Products and digital goods, payment by card, bank transfer or Ğ1 |
| Stripe | Card payments for shop and courses |
| June market | A community market where people offer goods and services for Ğ1 |
| Courses | Online courses with lessons, videos and saved progress |
You switch a module on with a few lines in app.sml and place it on a page with one element, such as ContactForm { } or Products { }. The blog is free like the rest of ForgeCMS. The other modules are free to try on your own computer and need a small one-time licence for a public website. Part III explains each module, and the licence chapter at its end explains why it is done this way.
Modules store what they must store, such as orders or newsletter addresses, as small files on your server. Still no database.
Where does what live? A cheat sheet
| You want to change… | Where |
|---|---|
| A text | Markdown file on Codeberg |
| What a page shows | The page's .sml file on Codeberg |
| Menu and footer | site.sml on Codeberg (or app.sml on older sites) |
| A blog post or an event | blog.sml or events.sml plus a Markdown file on Codeberg |
| Colours and fonts | Theme and style files on the server |
| Mail addresses, payments, modules | app.sml on the server |
When in doubt, describe the result you want to the AI. It knows this table too.
Pitfalls
- Putting design into texts. If you paste HTML into a Markdown file, it will work today and be a mess tomorrow. Ask for an SML element instead.
- Looking for an admin area. There is none for your pages. Codeberg is where you edit, the AI is where you ask. Only some modules, such as the newsletter or the market, have a small admin page of their own.
- Expecting changes in one second. Changes on Codeberg take a few minutes to appear. That is the price for never breaking.
What you learned
- A ForgeCMS site has four pieces: texts (Markdown) and pages (SML) on Codeberg, configuration (
app.sml) and the program on your server. - Text goes into Markdown, layout into SML.
app.smlis the only trusted file. Money, mail and rights are set there, never in the content.- ForgeCMS keeps a copy of every file, asks Codeberg only for changes, and keeps showing the last working version when something goes wrong.
- Features come as modules that are part of the system, not as plugins from strangers.
In Part II we turn this into a real website. First stop: a server of your own, for a few euros a month.
