Site Customization

DesertCMS separates editorial content, module settings, generated public files, and server configuration. Make routine site changes in the admin UI. Edit files only for theme development, custom modules, or deployment work.

Content

Use the admin editor for pages and posts:

• Pages are for durable site sections such as Home, About, Privacy, or Documentation landing pages.
• Posts are for dated stories and archive entries.
• Blocks store structured content instead of raw page templates.
• Publishing writes static HTML into the configured public root.
• Rebuild regenerates pages, indexes, archives, module pages, sitemap, robots.txt, redirects, and public assets.

Avoid editing generated files under the public webroot directly. They will be overwritten on publish or rebuild.

Navigation

Navigation is managed in the admin UI and stored in the database. Public module links may also be appended by the renderer when modules are enabled.

Common module paths:

/docs/
/gallery/
/forms/
/map/
/shop

If a manually managed nav item duplicates a module path, the renderer keeps one public link.

Theme Files

The editable theme copy lives under the configured theme_dir, usually:

/var/desertcms/themes/default/

The bundled default theme lives in the application tree:

/usr/local/www/desertcms/themes/default/

Editable theme files include:

templates/layout.html
templates/content.html
templates/index.html
templates/posts.html
templates/archive.html
assets/site.css
assets/map.js
assets/comments.js

The admin UI can update theme settings and selected theme files. For deeper theme work, edit the theme copy, then rebuild the public site.

Logos, Favicon, And Social Image

Upload logo, favicon, and social sharing images through the admin UI. Site settings store the public asset paths and the renderer injects them into generated pages.

Keep the image boundary:

• Original uploads stay private.
• Public pages reference generated derivatives.
• Favicon/logo/social assets are copied into the public asset tree only after processing.

Documentation

The Documentation module publishes Markdown files from the configured docs source directory.

Default source:

/usr/local/www/desertcms/docs

Admin path:

/admin/settings/modules/docs

Public path:

/docs/

Each .md file becomes a page under /docs/<slug>/. Use front matter to control ordering and summaries:

---
title: Custom Modules
summary: How to build first-party DesertCMS modules.
order: 50
---

# Custom Modules

Raw HTML in Markdown is escaped before publishing. Use Markdown syntax for links, lists, code, tables, images, and headings.

Module Settings

Optional modules are enabled from:

/admin/settings/modules

Modules with their own settings have dedicated pages:

/admin/settings/modules/shop
/admin/settings/modules/gallery
/admin/settings/modules/forms
/admin/settings/modules/docs
/admin/settings/modules/map

After saving module settings, DesertCMS rebuilds the public site so generated pages and navigation match the new state.

Redirects

Use the admin Redirects screen for URL changes. DesertCMS writes:

redirects.httpd.conf

into the public root. Copy the generated location blocks into the live OpenBSD httpd TLS server block and reload httpd after validation.

The CMS also writes static fallback redirect pages for simpler static environments.

Deployment Settings

Per-instance configuration lives in /etc/desertcms.conf or a site-specific config such as:

/etc/desertcms-desertcms.conf

Important paths:

data_dir
db_path
public_root
originals_dir
backup_dir
theme_dir
admin_asset_dir
docs_source_dir

Treat the config file as operational state. Do not store Stripe secrets, Postmark tokens, or app secrets in public docs or generated pages.

Backups

Use the maintenance command or admin backup screen before major changes:

doas su -m _desertcms -c 'env DESERTCMS_CONFIG=/etc/desertcms.conf perl /usr/local/www/desertcms/bin/desertcms-maint.pl backup'

Backups should include the SQLite database, private originals, editable themes, and configuration needed to recreate the instance.