ForgeCrowdBookWe don't sell the fish – we give you the rod.

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:

  1. looks up in its configuration which page belongs to /about,
  2. reads that page's SML file and the Markdown texts it uses,
  3. asks Codeberg whether any of these files have changed since last time,
  4. 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.sml is 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.