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 system/apps/chat/ keeps its upstream MIT license notice in that directory.

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

Navigation order follows the order of entries in navigation.yaml (including nested items).

Example:

---
template: default
title: About
slug: about
route: content/about.mu
summary: Suggested structure for an about page and contact details.
---

# 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, theme config, and built-in apps
• assets/: page-rendered images and other bundled assets

Important pieces:

• system/config/site_theme.py: shared colors, banner text, footer text, download/image styling, and other global 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/templates/apps/: dynamic app templates such as search and chat output
• system/apps/search/config.py: search-app-specific copy and presentation settings
• 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, ASCII images, comments, and embedded apps
• system/core/search_index.py: builds the generated search index used by site search
• system/core/comments_store.py: SQLite-backed storage helper for blog comments
• system/core/generate_wrappers.py: creates executable .mu wrappers from the Markdown content files during deployment
• system/apps/: dynamic app logic such as chat

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.

Blog comments are stored separately in NomadNet's storage directory as comments.db.

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
• searchable: optional boolean toggle for search indexing; set false to hide a page from site search
• comments: optional boolean toggle for post comments; defaults to enabled on post pages because the template includes ::comments::

Directives

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

• ::page_list ...::
• ::app name=...::
• ::downloads ...::
• ::ascii_image ...::
• ::comments::

This lets normal pages stay Markdown-first while still supporting NomadNet-specific features. Dynamic app output can also be embedded into normal content pages, for example:

::app name=chat::

Templates can also include directives. The default post template includes ::comments::, so blog posts show comments automatically unless frontmatter sets comments: false.

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

::downloads path=cms-starter::

Deployment

Deployment is handled by .forgejo/scripts/deploy.sh.

That script:

• copies content/, system/, and assets/ into NomadNet's page storage
• generates .mu wrappers from the Markdown files
• generates system/data/search_index.json for site search

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. In your Forgejo repository settings, add these secrets:
   • DEPLOY_SSH_KEY
   • DEPLOY_HOST
   • DEPLOY_USER
2. In your Forgejo repository settings, add these variables if you want to override the deploy script defaults:
   • SERVICE (default: reticulum.service)
   • TARGET_DIR (default: $HOME/.nomadnetwork/storage/pages)
   • FILES_DIR (default: $HOME/.nomadnetwork/storage/files)
   • ARCHIVE_TARGET_DIR if you also want each push to main to upload a zip archive to the server
3. Place any downloadable files directly in your node's storage/files directory. They are not copied from the repo.
4. Confirm the SSH user can run sudo systemctl stop/start for the NomadNet service.

The workflow streams the project files to the server over SSH and runs the deploy script remotely. No pre-existing checkout on the server is required.

For manual deploys without Forgejo CI, clone the repo directly on the server and run the deploy script:

chmod +x .forgejo/scripts/deploy.sh
./.forgejo/scripts/deploy.sh

You can override the defaults for one run:

SERVICE=reticulum.service \
TARGET_DIR="$HOME/.nomadnetwork/storage/pages" \
FILES_DIR="$HOME/.nomadnetwork/storage/files" \
./.forgejo/scripts/deploy.sh

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

If the ARCHIVE_TARGET_DIR variable is set, the same workflow also creates a zip archive from the tracked files in the pushed commit and uploads it to that directory on the deploy host before running the deployment. If ARCHIVE_TARGET_DIR is unset, the archive step is skipped.

Notes

• content/tests/ contains demo and compatibility pages that are intentionally kept out of the main navigation
• content/chat.md embeds the chat app through the normal content/template pipeline, with logic in system/apps/chat/
• if you add new page filenames, NomadNet may need a restart before they appear, depending on its page refresh settings