forgecms

command module
v0.0.0-...-963cf5d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 19 Imported by: 0

README

ForgeCMS

A simple website — no WordPress, no database, no PHP.

Your texts live as Markdown in a Git repo on Codeberg.
ForgeCMS turns them into HTML and serves the pages.

Recommended setup: a small IONOS VPS (often about €1/month entry offers)
where Claude Code builds the site and ForgeCMS runs it 24/7.
You only need a browser, SSH, and plain-language chat with the AI.


The easiest path: Claude Code on a €1 IONOS VPS

Working on a cheap always-on server is often simpler than juggling tools only on your laptop:

  • The website is already on the machine that will host it
  • Claude can install, compile, configure HTTPS, and restart services for you
  • Later edits: SSH in again → start Claude → describe the change
What you need
Item Notes
IONOS VPS Small Linux VPS (Ubuntu is fine). Entry prices are often around €1/month depending on the offer.
SSH access IP address + root password (or SSH key) from the IONOS Cloud Panel
Domain (optional) Point an A record to the VPS IP when you want https://yoursite.com
Anthropic / Claude access Account so Claude Code can log in (API key is easiest on a server)

You do not need to know Go, Nginx, or WordPress.


Step 1 — Order the VPS (IONOS)
  1. In the IONOS Cloud Panel, create a VPS.
  2. Choose a Linux image (e.g. Ubuntu).
  3. Note from the panel:
    • Public IP (e.g. 203.0.113.10)
    • root password (or set an SSH key)
  4. Wait until the server shows as running.

Official help: Connect to a Linux server via SSH (IONOS).


Step 2 — Log in with SSH

On your Mac (Terminal) or PC:

ssh root@YOUR.SERVER.IP

Accept the host key if asked, then enter the password.
You should see a Linux prompt (root@…).

Tip: Keep this SSH window open. All following commands run on the server, not only on your Mac.


Step 3 — Install Claude Code on the VPS

On the server:

npm install -g @anthropic-ai/claude-code

(Needs Node.js 18+. Install it first if npm is missing, e.g. via apt install nodejs npm or nvm.)

Check it's on the PATH:

claude --version
Sign in (server / no browser)

On a VPS you usually cannot complete a normal browser login easily.
Use an API key from your Anthropic account instead:

export ANTHROPIC_API_KEY="sk-ant-…"   # paste your real key
# Optional: put the same line in ~/.bashrc so it survives reconnects
echo 'export ANTHROPIC_API_KEY="sk-ant-…"' >> ~/.bashrc

Start Claude Code:

claude

(First-time install details: Claude Code docs.)


Step 4 — Ask Claude to build and deploy your site

In the Claude Code chat on the VPS, paste something like this (edit the placeholders):

Please read AI.md and README.md from the ForgeCMS project.

I am on a fresh IONOS Linux VPS. I want a live website on this machine.

1. Install tools you need (git, Go, Caddy or similar for HTTPS).
2. Clone https://codeberg.org/CrowdWare/ForgeCMS and read AI.md.
3. Build ForgeCMS (go build -o forgecms .).
4. Create a separate website project for me (not a messy copy of the CMS source):
   - app.sml, pages/*.sml, templates/, static/
   - Markdown content on Codeberg when useful
5. Use this website as structure/content inspiration:
   https://EXAMPLE.com
   (Recreate menu and pages with ForgeCMS. Do not copy trademarks or full
   copyrighted content 1:1 unless I own them.)
6. Run ForgeCMS so it starts on boot (systemd). Put the site under something
   clear like /opt/forgecms or /var/www/mysite.
7. Put a reverse proxy in front (Caddy is fine) with HTTPS for my domain:
   DOMAIN: yoursite.com
   (If DNS is not ready yet, serve on the server IP / HTTP first and explain DNS.)
8. Tell me in plain language:
   - the public URL
   - where the files live
   - how I edit texts on Codeberg
   - how I SSH back and change something later with Claude

Domain: In your DNS (IONOS or registrar), set an A record:
yoursite.com → YOUR.SERVER.IP.
Claude / Caddy can then issue a free HTTPS certificate once DNS has propagated.


Step 5 — Open the site

When Claude is done, open the URL it gave you (domain or http://YOUR.SERVER.IP).
Refine in the same chat:

Add /contact and embed this YouTube video: https://www.youtube.com/watch?v=…
Make the colours dark blue and update the footer year.
Push the site project to a new Codeberg repo and give me the link.

Coming back 6 months later (you forgot how this works)

This is normal. You do not need to re-learn ForgeCMS.

What you still have
  • The VPS (always on) and SSH access
  • The site files on the server and/or on Codeberg
  • Claude Code (reinstall in one command if needed)

You do not need a WordPress login.

What to do
  1. SSH into the server: ssh root@YOUR.SERVER.IP
  2. Go to the site folder (Claude told you the path; often under /opt/… or /var/www/…).
  3. Start Claude: export ANTHROPIC_API_KEY="…" if needed, then claude
  4. Paste:
This is my ForgeCMS website on this VPS. I last touched it months ago and I
don't remember how it works. Please:

1. Read AI.md (clone ForgeCMS from Codeberg if needed).
2. Explain in plain language: which files control the menu, home page, and text.
3. Make the following change(s):
   - …
4. Restart or reload ForgeCMS if needed so the live site updates.
5. Summarise what you changed in simple words.
6. If useful, commit and push to Codeberg.
Typical small changes
You want… Where it usually lives
New wording on the home page Markdown on Codeberg and/or pages/index.sml
New page in the menu new ….sml + Route and Item in site.sml on Codeberg (see "Menu, footer and routes" below); older sites without site.sml: app.sml
Colours / fonts static/style.css and/or theme SML
YouTube video YouTube { … } in a page SML file
New event / gig events.sml in the content repo (see "Add an event" below)
New blog post blog.sml + a Markdown file in the content repo (see "Write a blog post" below)
Blog share buttons on/off share: in Blog { … } in the site's app.sml (see "Write a blog post" below)
Contact form fields Contact { Field { … } } in the site's app.sml (see "Contact form and newsletter" below)
Send a newsletter /newsletter/admin on your site (see "Contact form and newsletter" below)
Imprint / privacy text Markdown file or that page's content

Describe the result in everyday language. Claude maps it to files and restarts services if needed.

If the site is down
The website does not load. Please check ForgeCMS and the reverse proxy (Caddy),
fix what is broken, restart services, and tell me the URL and what was wrong.

Edit your texts on Codeberg (Markdown)

Your wording usually lives in Markdown files (.md) on Codeberg —
not in a WordPress admin. Layout (menu, structure) lives in the site project; texts in Markdown.

You can change texts in the browser, with no SSH and no AI.

1. Open the content repo
  1. Log in at codeberg.org.
  2. Open the repository that holds your Markdown
    (your agency/Claude will give you the link).
  3. Open the file, e.g. home.md, about.md, impressum.md.
2. Edit in the web UI
  1. Click the file name.

  2. Click the pencil (Edit file).

  3. Change the text. A few Markdown marks:

    You type Result
    # Title Big heading
    ## Section Smaller heading
    blank line New paragraph
    **bold** bold
    *italic* italic
    [Link text](https://…) A link
    - item Bullet list
  4. Commit message, e.g. Update opening hours → Commit changes.

3. See it on the live site

ForgeCMS loads Markdown from Codeberg and caches it. After you commit:

  • Reload the page (once or twice).
  • If it stays old, SSH + Claude: "Refresh the ForgeCMS content cache and restart if needed."

You do not recompile the whole CMS for a typo.

4. Add an event (events module)

If your site lists dates, events or performances, they all live in one file in the content repo, usually events.sml. Each event is one block:

Event {
    id:     "2026-10-12-concert"            // unique, lower case, digits and - only; becomes the web address
    title:  "Concert in the park"
    start:  "2026-10-12 19:30"              // or just "2026-10-12" for a whole day
    end:    "2026-10-12 22:00"              // optional
    place:  "Stadtpark, Berlin"             // optional
    image:  "termine/2026-10-12-flyer.jpg"  // optional flyer or photo
    teaser: "Open air with friends."        // optional short text for the list
    text:   "termine/2026-10-12-concert.md" // optional long description (Markdown)
}
  1. Upload the flyer or photo (JPG or PNG) into static/termine/ in the repo.
  2. Open events.sml, copy an existing Event { … } block, change the values.
  3. Optional: add a Markdown file with the long description and point text: at it.
  4. Commit changes. The list sorts itself: upcoming events first, past events below. You never have to move or delete old events.

Headings and button texts (e.g. "Upcoming gigs") are in the Labels { … } block at the top of the same file — change them there, in every language your site has.

5. Write a blog post (blog module)

A blog keeps its list of posts in one file in the content repo, usually blog.sml; the text of each post is its own Markdown file. This works from a phone in the Codeberg web interface, too.

Post {
    id:     "day-12-lyon"            // unique, lower case, digits and - only; becomes the web address
    title:  "Day 12: Lyon"
    date:   "2026-10-12"             // or "2026-10-12 19:30"
    place:  "Mâcon → Lyon"           // optional
    image:  "blog/day-12.jpg"        // optional photo (JPG or PNG) below static/
    teaser: "Rain, then sun."        // optional short text for the list
    text:   "blog/day-12-lyon.md"    // the post itself (Markdown)
}
  1. Upload the photo into static/blog/ (Add file → Upload file). Photos inside the text: ![What you see](/static/blog/day-12-market.jpg) in the Markdown.
  2. Create the Markdown file (Add file → New file, e.g. blog/day-12-lyon.md).
  3. Open blog.sml, copy a Post { … } block, change the values, Commit changes. The newest post is shown first automatically.

Not ready yet? Add draft: "true" to the block. A date in the future publishes the post by itself on that day.

Share buttons under every post are optional. Switch them on in the site's app.sml (the site project on the VPS, not the content repo), listing the ones you want in the order they should appear:

Blog {
    path:  "/blog"
    share: "whatsapp telegram facebook x bluesky linkedin email copy"
}

They are plain links: no Facebook or other third-party scripts, no cookies, no tracking, so no cookie banner is needed. copy copies the post's address; phones also get a "Share …" button for their own share menu. Leave share out and there are no buttons. The buttons use the classes blog-share and blog-share-btn, so their look can be adjusted in the site's style.css.

6. Contact form and newsletter

The contact form is described once in the site's app.sml (the site project on the VPS) and placed on any page with ContactForm { }:

Contact {
    to: "me@example.com"
    Field { name: "name"  type: "text"     label: "Name"   required: true }
    Field { name: "email" type: "email"    label: "E-Mail" required: true }
    Field { name: "topic" type: "radio"    label: "Thema"  options: "Kurs, Coaching, Sonstiges" }
    Field { name: "text"  type: "textarea" label: "Nachricht" required: true }
    Field { name: "news"  type: "newsletter" }
}

Field types: text, email, tel, textarea, checkbox, radio, select and newsletter (a "Yes, send me the newsletter" box). Messages arrive by mail; you can answer them directly, the reply goes to the visitor.

Spam: the form drops posts that arrive less than 3 seconds after the page was opened — bots send at once, people need longer. Change it with min_seconds: 5 in Contact { } (0 switches it off).

Newsletter: add Newsletter { admins: "me@example.com, partner@example.org" privacy: "/datenschutz" } to app.sml. People sign up with the box in the contact form or with NewsletterForm { } on any page; they get a mail and are only on the list after clicking the link in it (required by law in the EU — mention the newsletter in your privacy policy). To write to everyone, open https://<your-site>/newsletter/admin, log in with one of the admins addresses, write subject and text (Markdown: # heading, **bold**, [link](https://…)), check the preview, send yourself a test mail, then tick the box and Send. The mails go out one per second in the background; the page shows the progress. Every mail has an unsubscribe link.

7. A marketplace (June-Markt)

A community market where people offer goods and services for Ğ1 (June) or post requests ("Gesuche"). Add to app.sml:

Market {
    title:  "June-Markt"
    admins: "me@example.com, partner@example.org"
    terms:  "/markt/regeln"
    privacy: "/datenschutz"
    featuredTags: "lebensmittel handwerk software"
}

and a page markt.sml with Market { } on the route /markt. Vendors click "Angebot einstellen", log in with the link they get by mail, fill in name, place and (optionally) their Ğ1 wallet, and post listings with photos and hashtags (#software #massage #bandsuchtgitarist). Visitors search, filter by hashtag or place and write to the vendor through a form — the vendor's address stays hidden until they answer. Buyers pay the vendor's wallet directly; the site never touches the money. Vendors whose wallet belongs to a certified Ğ1 member get a ✓ badge.

Direct purchase and a fee for you: add wallet: "g1…" (your market wallet) and fee: "3%" to Market { }. Vendors can then tick "allow direct purchase" on a listing (accepting the fee). Buyers order on the listing page and pay the vendor's wallet with the order number in the comment; ForgeCMS sees the payment and mails both sides. On the 1st of every month each vendor gets a statement of the fees, payable to your market wallet; if it stays unpaid past the due date (feeDue, 30 days) the vendor's listings are hidden until it is paid.

You moderate at https://<your-site>/markt/admin (log in with an admins address): the first listing of every new vendor waits for your OK, reports from visitors land there too, and you can remove listings or block vendors. Write the market rules on /markt/regeln and mention the market in your privacy policy.

When the site's app.sml says layout: "site.sml" in its Site { … } block, the menu, the footer and the list of pages live in site.sml in your content folder on Codeberg — you change them like any text:

Site {
    Menu {
        Item { label: "Start"  label_en: "Home"  href: "/" }
        Item { label: "Blog"   href: "/blog" }
    }
    Footer {
        text: "© 2026 My Site"
        Link { label: "Impressum"  label_en: "Legal notice"  href: "/impressum" }
    }
    Routing {
        Route { path: "/"           page: "index.sml" }
        Route { path: "/impressum"  page: "impressum.sml" }
    }
}

A new page = a new .sml file, a Route for it and (if it should show up in the menu) an Item. Changes are live within about 5 minutes. If the file has a typo, the site keeps showing the last working version — nothing breaks; check that your change appears, and if not, look for a missing } or ".

Layout vs content
Change Where
Article text Markdown on Codeberg
Menu, footer, new routes site.sml on Codeberg when the site has one (see below), otherwise app.sml on the VPS
Colours, YouTube block, modules Site project on the VPS (often with Claude)

Markdown files should stay plain text (headings, bold, links, lists) — no HTML tags, no CSS, no JavaScript. Buttons, pricing cards, code samples and other layout belong in the page's .sml file as SML elements instead; see AI.md §0.3/§6 if Claude needs to add a new one.


What you end up with

Piece Role
IONOS VPS (~€1 class) Always-on Linux box
Claude Code AI that installs, builds, edits, deploys
ForgeCMS Serves the website
Site files app.sml, pages/, templates, static
Codeberg Markdown Texts you edit in the browser
Caddy (or similar) HTTPS + reverse proxy in front of ForgeCMS

No admin backend, no plugin jungle — files in Git, process on a small VPS.


Alternative: only on your laptop

Fine for experiments; production is usually nicer on the VPS.

  1. Install Claude Code on your Mac/PC:
    npm install -g @anthropic-ai/claude-code
  2. Run claude and use a prompt similar to Step 4, but ask for local preview
    (http://localhost:8080) first; deploy to the VPS when you are ready.
Tool Install / docs
Claude Code (recommended) npm install -g @anthropic-ai/claude-code

Manual path (without AI)

git clone https://codeberg.org/CrowdWare/ForgeCMS.git
cd ForgeCMS
go build -o forgecms .
./forgecms --config ./app.sml

Requires Go 1.22+.
On a VPS, put a reverse proxy (e.g. Caddy) in front and run ForgeCMS under systemd
(see forgecms.service / setup-server.sh in this repo).
Full technical detail: AI.md.


License

Copyright (C) 2026 CrowdWare — art@crowdware.info


Documentation

File Who it's for
This README People — IONOS VPS + Claude Code, content edits, return later
AI.md (see version inside) AI assistants & technical detail
forge-cms-spec.md Formal specification

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
internal
auth
Package auth provides passwordless visitor accounts for a site: a user proves an email address by clicking a magic link and then carries a signed session cookie.
Package auth provides passwordless visitor accounts for a site: a user proves an email address by clicking a magic link and then carries a signed session cookie.
bank
Package bank holds small helpers for euro bank transfers (SEPA): IBAN checks and formatting.
Package bank holds small helpers for euro bank transfers (SEPA): IBAN checks and formatting.
blog
Package blog implements the blog module (see CWUP/tasks/blog.md): posts listed from one SML file of the content repo, newest first, with a page per post and an Atom feed.
Package blog implements the blog module (see CWUP/tasks/blog.md): posts listed from one SML file of the content repo, newest first, with a page per post and an Atom feed.
contact
Package contact renders and checks the ContactForm element: a form built from the Contact{} block of app.sml (see CWUP/tasks/contact_newsletter.md).
Package contact renders and checks the ContactForm element: a form built from the Contact{} block of app.sml (see CWUP/tasks/contact_newsletter.md).
courses
Package courses is the online course module (see CWUP/tasks/courses.md).
Package courses is the online course module (see CWUP/tasks/courses.md).
events
Package events implements the events module (see CWUP/tasks/events.md): dates, events and performances listed from one SML file of the content repo, with a page and a calendar file per event.
Package events implements the events module (see CWUP/tasks/events.md): dates, events and performances listed from one SML file of the content repo, with a page and a calendar file per event.
features
Package features keeps feature requests and their votes (see CWUP/tasks/feature_requests.md).
Package features keeps feature requests and their votes (see CWUP/tasks/feature_requests.md).
g1
Package g1 holds small helpers for the Ğ1 (June) libre currency on Duniter v2: address format checks and amounts in centimes.
Package g1 holds small helpers for the Ğ1 (June) libre currency on Duniter v2: address format checks and amounts in centimes.
market
Package market keeps the listings of the marketplace module (see CWUP/tasks/june_market.md): vendors, their listings with images, and reports from visitors.
Package market keeps the listings of the marketplace module (see CWUP/tasks/june_market.md): vendors, their listings with images, and reports from visitors.
modules
Package modules is the catalog of ForgeCMS's paid modules (modules.sml): what each one does, what it costs in EUR and June, what it needs and how it is switched on.
Package modules is the catalog of ForgeCMS's paid modules (modules.sml): what each one does, what it costs in EUR and June, what it needs and how it is switched on.
newsletter
Package newsletter keeps the mailing list of a site and sends mailings (see CWUP/tasks/contact_newsletter.md).
Package newsletter keeps the mailing list of a site and sends mailings (see CWUP/tasks/contact_newsletter.md).
share
Package share builds share buttons for a page: one plain link per service (or a button for "copy"), no third-party scripts, no cookies.
Package share builds share buttons for a page: one plain link per service (or a button for "copy"), no third-party scripts, no cookies.
shop
Package shop implements the Ğ1 shop module (see CWUP/tasks/g1_shop.md).
Package shop implements the Ğ1 shop module (see CWUP/tasks/g1_shop.md).
stripe
Package stripe is the Stripe payment module (see CWUP/tasks/courses.md): hosted Stripe Checkout, webhook verification and a registry through which other modules (courses, shop) learn that a payment went through.
Package stripe is the Stripe payment module (see CWUP/tasks/courses.md): hosted Stripe Checkout, webhook verification and a registry through which other modules (courses, shop) learn that a payment went through.
video
Package video turns YouTube and PeerTube URLs into embeds.
Package video turns YouTube and PeerTube URLs into embeds.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL