NomadNet CMS Starter

This repository is a small, customizable base for building NomadNet sites.

It is licensed under the GNU GPL v3 or later. The bundled chat app in apps/chat/ is also GPL-licensed and includes its upstream license notice.

The main idea is:

• write page content in Markdown
• keep layout in Micron templates
• keep colors, banner text, and other shared presentation settings in one theme file
• generate the small .mu route wrappers automatically during deployment

That makes the site easier to clone, restyle, and extend without writing most page content directly in Micron.

How To Use It

For normal content work, most edits happen in content/.

To add or edit a page:

1. Create or edit a Markdown file in content/
2. Add frontmatter at the top
3. Write the page body in Markdown
4. Add the page to system/config/navigation.yaml if it should appear in the main navigation

Example:

---
template: default
title: About
slug: about
route: content/about.mu
summary: About this node and how to get in touch.
---

# About

This page is written in Markdown.

How It Works

The repo is split into three main parts:

• content/: authored Markdown pages
• system/: renderer, templates, navigation config, and theme config
• apps/: dynamic application pages such as chat

Important pieces:

• system/config/site_theme.py: shared colors, banner text, footer text, download/image styling, and other theme values
• system/config/navigation.yaml: main navigation
• system/templates/pages/: full page templates
• system/templates/fragments/: shared Micron fragments like header and footer
• system/core/page_renderer.py: loads content, renders Markdown, applies templates, and injects shared context
• system/core/directives.py: custom directives such as page lists, downloads, and ASCII images
• system/core/generate_wrappers.py: creates executable .mu wrappers from the Markdown content files during deployment

Markdown is the default authoring format. Micron is mainly used as the rendered output format and for shared layout templates.

Assets And Downloads

This starter keeps page-rendered assets in assets/.

Real downloadable files are expected to live in NomadNet's storage/files directory on the node that serves the site. The downloads directive reads directly from that live storage/files tree.

Templates And Frontmatter

Each content page can choose a template in frontmatter:

• default
• landing
• post
• minimal

Common frontmatter fields:

• title: page title
• slug: logical page name
• route: generated .mu route path
• summary: short description used by templates and page lists
• template: which page template to use
• section: optional grouping, used for things like blog post listings
• date: optional post date

Directives

Special page behavior lives in directives inside Markdown, for example:

• ::page_list ...::
• ::downloads ...::
• ::ascii_image ...::

This lets normal pages stay Markdown-first while still supporting NomadNet-specific features.

For downloads, point the directive at a path under NomadNet's storage/files, for example:

::downloads path=my-downloads::

Deployment

To deploy this starter, copy content/, system/, apps/, and assets/ into your NomadNet pages directory and then run system/core/generate_wrappers.py against the copied content/ tree.

Because NomadNet serves files by path, those generated wrappers are what make pages available as /page/....

Downloadable files are not mirrored from the repo. They should be placed directly in NomadNet's storage/files directory, where the downloads directive can find them and where they become available through :/file/....

Forgejo Deployment

This starter includes example deployment files in .forgejo/.

To use them:

1. Put a checkout of this repo on the machine that runs your NomadNet node.
2. Edit .forgejo/scripts/deploy.sh and set:
   • REPO_DIR to the checkout path on the target machine
   • BRANCH to the branch you want to deploy
   • SERVICE if your NomadNet service name is not reticulum.service
   • TARGET_DIR and FILES_DIR if your NomadNet storage paths differ
3. Place any downloadable files directly in your node's storage/files directory. They are not copied from the repo.
4. Make sure the deploy script is executable:

   chmod +x .forgejo/scripts/deploy.sh
   

5. In your Forgejo repository settings, add these secrets:
   • DEPLOY_SSH_KEY
   • DEPLOY_HOST
   • DEPLOY_USER
6. Confirm the SSH user can run the deploy script and restart the NomadNet service.

The workflow in .forgejo/workflows/deploy.yml deploys on pushes to main, connects over SSH, and runs the deploy script on the target machine.

Notes

• content/tests/ contains demo and compatibility pages that are intentionally kept out of the main navigation
• apps/chat/ is a dynamic app and is separate from the Markdown content pipeline
• if you add new page filenames, NomadNet may need a restart before they appear, depending on its page refresh settings