LightCMS

LightCMS is a Go-powered content management system built for the AI era. It's simultaneously AI-native (semantic search, built-in Claude-powered chat widget, MCP server for agent control), agentically controllable (Claude Code and any MCP client can read, write, publish, and bulk-import content via 106 MCP tools), and agentically updatable (the codebase is clean, well-structured Go — coding agents can safely extend it). For teams that want a CMS that works with AI rather than around it.

What's New in v7.1

Feature	Summary
Ambient Copilot	The copilot is a slide-in drawer on every admin page — floating 🤖 button, fullscreen toggle, ChatGPT-style searchable chat history, live typing indicator, and rendered tables. It edits, creates, publishes, and reads analytics and maintenance reports in plain language.
Analytics Ranges	60/90-day presets and custom date ranges across all analytics views.
Fast AI-Crawler Endpoints	llms.txt serves in ~1 second on large sites (projected queries), and homepages emit schema.org WebSite JSON-LD with SearchAction.
Version Visibility	The admin sidebar shows the running version.

What's New in v7.0

Feature	Summary
Agent Sandbox ("PRs for content")	Agents work in an isolated fork with copy-on-write; humans review a per-field diff and merge. Live content is untouchable until merge.
Agent Governance	Scoped API keys, sandbox-only keys (server-enforced), per-session change ledger with one-call rollback, and per-version provenance (human vs agent, which session).
Admin Copilot	`/cm/copilot` — edit, create, and publish content in plain language, with RBAC and full audit logging.
llms.txt + JSON-LD	Auto-generated `/llms.txt` and `/llms-full.txt` for AI crawlers, schema.org structured data on every page.
MCP for Readers	Public read-only MCP endpoint at `/mcp-public` — visitors' agents can search and read the site natively.
Local Embeddings	`LIGHTCMS_EMBEDDINGS_PROVIDER=ollama` for fully self-hosted semantic search — no API credits.
Self-Maintaining Sites	Daily maintenance scans surface stale pages, missing meta, and broken links as an agent-ready work queue.

What's New in v6.0

Feature	Summary
Content Approvals	Contributors submit content for approval; editors/admins approve or reject from `/cm/approvals`. Rejection comments auto-post to the discussion thread.
Contributor Role	New RBAC role between Viewer and Editor. Can create content + upload assets (pending), post comments, and submit for approval — but cannot publish directly or manage system settings.
Approval Workflows	Configurable trigger-based workflows (contributor, folder path, template ID, or tag). Sequential or concurrent mode with configurable approver lists.
Content Discussion	Inline comment thread at the bottom of every edit page. @mention autocomplete, live badge count, admin delete.
Tabbed Bottom Panel	Discussion, Version History, and Forks organized into tabs on the content edit page.
Approvals Dashboard	My Queue + Other Pending + Workflow Config at `/cm/approvals`. Sidebar badge shows pending count.
Dashboard Sections	Requiring Approvals and Recent Comments appear on the admin dashboard when relevant.
New Webhook Events	`comment.created`, `content.pending_approval`, `asset.pending_review`.
14 new MCP tools	Full comment and approval lifecycle — list/create/delete comments, full workflow CRUD, list/get/submit/approve/reject/cancel approval requests.

What's New in v5.0

Feature	Summary
Import Pipeline	Three new import types — RSS/Atom feeds, Markdown/ZIP upload, CSV bulk import — with a unified job dashboard at `/cm/imports`.
RSS/Atom Import	Configure recurring feed sources with hourly/daily/weekly schedules, template mapping, folder targeting, and auto-publish.
Markdown Import	Upload `.md` files or `.zip` archives with YAML frontmatter. Supports Notion exports, Obsidian vaults, Hugo/Jekyll migrations, and AI-generated content.
CSV Import	Upload CSV files and map columns to content fields. Specify the title column; all other columns become fields automatically.
Real-time Job Status	SSE-powered live log stream at `/cm/imports/{jobID}`. Watch imports happen line-by-line or review full history after the fact.
10 new MCP import tools	`list_import_sources`, `create_import_source`, `update_import_source`, `delete_import_source`, `trigger_import_source`, `import_markdown`, `import_csv`, `list_import_jobs`, `get_import_job`, `cancel_import_job`.
Agentic bulk content creation	`import_markdown` is designed for AI agents to generate and import large content batches in a single call. See MCP.md.
Deduplication	Imports match by `full_path` — re-importing the same slug updates rather than duplicates.

What's New in v4.5

Feature	Summary
Webhooks	HMAC-SHA256 signed events for `publish`, `unpublish`, `delete`, `create`, `update`. Admin UI at `/cm/webhooks` with delivery history and a docs page.
Scheduled Publishing	Set a future `publish_at` timestamp on any content item; a background scheduler auto-publishes at the right time.
Content Locking	Advisory lock when editing (30-min expiry). Warning banner if another user is already editing. Admins can force-unlock.
Incremental Static Regeneration (ISR)	Template layout changes regenerate affected pages in 20-page batches, preventing server overload on large sites.
Edge Caching Headers	ETag, Cache-Control, Last-Modified, and Vary headers on all public pages. 304 Not Modified support.
Cloudflare Integration	Configure Zone ID + API Token to auto-purge Cloudflare cache on publish/unpublish.
Structured JSON Logging	All server logs emit structured JSON with `timestamp`, `level`, `message`, and context fields.
Rate Limit Dashboard	New tab on the audit log page showing locked IPs, attempt counts, and a one-click clear button.
MCP Prompt Resources	Three new MCP resources: `lightcms://site/structure`, `lightcms://content/recent`, `lightcms://theme/config`.

Why LightCMS?

Lightweight: A clean, focused codebase that's easy to understand, modify, and extend. No bloated frameworks or complex abstractions.

AI-Native: Built from the ground up for the AI era:

MCP Integration: Full Model Context Protocol server with 106 tools and 3 prompt resources for website management. Supports both local stdio and HTTP streamable transports — connect from Claude Code, Claude Desktop, or any MCP-compatible client.
OAuth 2.1 for Remote Agents: Sandboxed desktop apps like Claude's Cowork can securely connect over HTTP using OAuth 2.1 with PKCE. No embedded passwords — just authorize once and the agent manages your site.
Fork-Friendly: Designed to be forked and customized by Claude Code. Ask Claude to add new content types, modify templates, or build custom features — the codebase is structured for AI-assisted development.
Natural Language Website Management: Skip the admin UI entirely. Create pages, manage assets, customize themes, and publish content through conversation.

Features

Content Management

Template System: Define reusable content structures with custom fields (text, richtext, image, date, select, markdown)
Static Page Generation: Fast page loads from pre-rendered HTML — no runtime templating overhead
Content Versioning: Full version history with diff comparison and one-click revert
Soft Delete: Recover deleted content with undelete functionality
Content Tagging: Tag any content item with one or more freeform labels, then query by tag across your site
Snippets: Named HTML template fragments used as reusable rendering units in dynamic queries
lc:query Directives: Embed live content queries directly in template layouts — at publish time they expand into rendered lists of matching pages
Content Collections: Auto-generated paginated listing pages filtered by category
Folders & URL Organization: Hierarchical content organization with clean URL paths
Rich Text Editor: TinyMCE integration for visual content editing
Regex Search & Replace: Site-wide or scoped search-and-replace with RE2 regex support, capture groups, and mandatory preview step
Bulk Operations: Update or apply field operations across up to 100 pages in a single API call; export/transform/re-import pipelines
Scheduled Publishing (v4.5+): Set a future publish_at timestamp; a background scheduler auto-publishes at the right time
Content Locking (v4.5+): Advisory lock while editing (30-min expiry); warning banner if another user holds the lock; admins can force-unlock
Incremental Static Regeneration (v4.5+): Template layout changes regenerate pages in 20-page batches to prevent server overload on large sites

Import Pipeline (v5.0+)

RSS/Atom Feed Sources: Configure recurring import sources with configurable schedule (hourly/daily/weekly), template mapping, folder targeting, and auto-publish. Manage sources and run history from /cm/imports.
Markdown + ZIP Import: Upload .md files or .zip archives of Markdown. YAML frontmatter in each file controls title, slug, folder, template, tags, and scheduled publish time. Supports Notion exports, Obsidian vaults, Hugo/Jekyll site migrations, and AI-generated content.
CSV Bulk Import: Upload a CSV and specify which column is the title; all other columns are stored as content fields automatically.
Real-time SSE Job Status: Live log stream at /cm/imports/{jobID} — watch imports happen line-by-line or review full history after the fact.
MCP-first Design: import_markdown is specifically designed for AI agents to generate and import large content batches in a single call, replacing dozens of create_content calls with one import_markdown + one get_import_job. See MCP.md for workflow examples.

Content Forks (v4.0+)

Fork Workspaces: Create named staging workspaces where sets of page edits can be authored, previewed, and reviewed before going live
Sparse Model: Only edited pages live in a fork — unmodified pages fall through to live content automatically
Fork Preview Mode: Activate via a floating bar injected into the live site; a cookie routes all page requests through the fork so you see exactly how the site will look after merge
Merge with Conflict Detection: Admins merge forks into live content; if a live page was changed after the fork was created, the conflict is recorded (fork wins). New pages created in the fork are inserted into live on merge
Full MCP Toolset: 8 dedicated fork tools — list_forks, create_fork, get_fork, fork_page, remove_fork_page, merge_fork, archive_fork, delete_fork

Batch & Parallel Operations

Designed for agents that prefer parallelized, high-throughput workflows over sequential single-item calls:

bulk_update_content: Update up to 100 pages in a single API call. Each item uses merge semantics — only the fields you specify are touched. Supports dry_run validation before committing, and auto_republish to re-publish all previously-published pages in the same call, eliminating a separate publish step
bulk_field_operation: Apply a single operation (set, clear, prepend, append, wrap) to a field across every matching page in one call. Scope by template, folder, category, or explicit ID list. Ideal for adding disclaimers, updating metadata, or clearing stale fields across a content type
publish_multiple: Publish a list of IDs — or all drafts at once with publish_all_drafts: true — in a single request instead of looping over publish_content
export_content: Dump full field data for a scoped set of pages as a structured JSON array. Designed for export → transform → re-import pipelines; pair with bulk_update_content for large-scale content migrations
Scoped Search & Replace: Both scoped_search_replace_preview and scoped_search_replace_execute accept scope filters (folder, template, category, IDs) so agents can target precise subsets rather than running site-wide operations
Parallel-Safe Read API: list_content with include_data: true returns full field values in one fetch; agents can fan out reads across multiple list_content / get_content calls concurrently and then batch-write with bulk_update_content

Recommended agent pattern for large updates: list_content → transform in parallel → bulk_update_content (up to 50/call) → publish_multiple.

AI Chat Widget (v4.2+)

Embeddable Widget: Add a floating AI chat bubble to any page with a single <script> tag — self-contained, no build step required
Two-Phase Pipeline: Each visitor query runs hybrid semantic+fulltext search to retrieve relevant content excerpts, then streams those excerpts through Claude Haiku for a conversational synthesized answer
SSE Streaming: Haiku's token-by-token output is forwarded live to the browser via Server-Sent Events; falls back to plain JSON for non-SSE clients
AI-Optional: Without an Anthropic API key, the widget works as a search-in-chat experience returning ranked excerpts — no API cost
Fully Configurable: Admin "Chat Widget" page controls title, welcome message, placeholder text, primary color, position (bottom-left/right), max results, and editable system/user prompt templates
Dedicated Rate Limiting: Separate per-IP (5/min) and global (30/min) limiters independent from the search and API limiters
Source Attribution: Every response includes the content pages whose excerpts were used, with titles and paths

Multi-User Access Control & Approvals (v2.0+, v6.0+)

Role-Based Access Control (RBAC): Four roles — admin, editor, contributor, viewer — with granular permission enforcement on all admin UI pages and REST API endpoints
Contributor Role (v6.0+): Create content, upload assets, post comments, and submit for editorial approval — without publish rights
Approval Workflows (v6.0+): Configurable trigger-based workflows (by role, folder, template, or tag). Sequential or concurrent mode. Default (no workflow): any editor or admin can approve
Content Approvals Dashboard (v6.0+): My Queue, Other Pending, and Workflow Config at /cm/approvals. Sidebar badge shows pending count
Content Discussion (v6.0+): Inline threaded comments on every content edit page. @mention autocomplete, admin delete, live count badge
User Management: Admin panel for creating users, assigning roles, disabling accounts, and resetting passwords
Audit Log: Persistent, searchable log of all mutations (who did what, when) with 365-day retention
Rate Limit Dashboard (v4.5+): New tab on the audit log page showing locked IPs, attempt counts, and a clear button
User-Scoped API Keys: API keys inherit the permissions of their owning user
Force Password Change: Temporary passwords trigger a mandatory change on first login

Smart End-User Search

Hybrid Search: Combines full-text exact matching with semantic vector search (Voyage AI embeddings), merged via reciprocal rank fusion
Configurable Ranking: All ranking weights editable in the admin panel — nav boost, title boost, boosted templates, demoted path prefixes, and penalty scores
Intelligent Defaults: Nav-linked pages surface first, concept-template pages rank above generic content, video transcripts are deprioritised
Title Boost: Pages where the query appears in the title always rank above body-only matches
Typeahead Suggestions: Fast prefix-matching suggestions — pages for direct navigation, keywords for full search — with the same structural ranking
Works Without Embeddings: Falls back to full-text search if no Voyage API key is configured
Rate Limiting: Per-IP and global rate limiting for DDoS protection

Developer & Integration

REST API: Full /api/v1/ JSON API with API key and OAuth token authentication, RBAC-enforced
MCP Server: 106 tools + 3 prompt resources for agentic website management (stdio + HTTP streamable)
OAuth 2.1: Authorization code flow with PKCE for remote MCP clients — no embedded passwords
CLI Tool: Command-line interface for all content management operations
URL Redirects: 301/302 redirect rules managed from the admin panel
Webhooks (v4.5+): HMAC-SHA256 signed event delivery for 6 event types (content.create, content.update, content.publish, content.unpublish, content.delete, and more); per-webhook secrets; delivery history with retry visibility; admin UI at /cm/webhooks
Cloudflare Integration (v4.5+): Auto-purge Cloudflare cache on publish/unpublish via Zone ID + API Token
Edge Caching Headers (v4.5+): ETag, Cache-Control, Last-Modified, Vary, and 304 Not Modified on all public pages
Structured JSON Logging (v4.5+): All server logs emit structured JSON with timestamp, level, message, and context fields

Site Customization

Theme Customization: Colors, fonts, border radius, custom CSS — all editable in the admin panel with version history
Header/Footer HTML: Full HTML control over site chrome injected around all pages
Asset Management: Upload and manage images, documents, and other files with path-based serving

Prerequisites

Go 1.24 or later
MongoDB Atlas account (free tier works great)

Quick Start

Clone the repository
Copy config.dev.json.example to config.dev.json
Edit config.dev.json with your MongoDB connection string
Run go run cmd/server/main.go
Visit http://localhost:8082/cm and log in with your email and password
On first run, an admin account is created — set LIGHTCMS_ADMIN_EMAIL to use your email, or it defaults to admin@localhost

MongoDB Atlas Setup

Step 1: Create an Atlas Account

Go to MongoDB Atlas
Sign up for a free account (no credit card required)

Step 2: Create a Cluster

Click "Build a Database"
Select "M0 FREE" (Shared) tier
Choose your preferred cloud provider and region (closest to you)
Click "Create Deployment"

Step 3: Set Up Database Access

Create a database user:
- Username: lightcms (or your choice)
- Password: Generate a secure password (save this!)
- Click "Create User"
Add your IP address:
- Click "Add My Current IP Address"
- Or add 0.0.0.0/0 to allow access from anywhere (less secure, but convenient for development)
- Click "Finish and Close"

Step 4: Get Your Connection String

Click "Connect" on your cluster
Select "Drivers"

Copy the connection string, it looks like:

mongodb+srv://lightcms:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority

Replace <password> with your actual password

Step 5: Create Your Config File

For development, copy the example and fill in your values:

cp config.dev.json.example config.dev.json

Edit config.dev.json:

{
  "port": "8082",
  "mongo_uri": "mongodb+srv://lightcms:[email protected]/lightcms",
  "env": "development",
  "session_secret": "any-random-string-for-dev"
}

For production, use config.prod.json:

cp config.prod.json.example config.prod.json

Edit with production values (use openssl rand -hex 32 for session_secret).

Installation

# Clone or navigate to the project
cd lightcms

# Install dependencies
go mod tidy

# Run the server
go run cmd/server/main.go

Or use the run script:

./run.sh

Configuration

LightCMS uses JSON config files. Create either:

config.dev.json - for development
config.prod.json - for production (takes precedence if both exist)

Field	Description
`port`	Server port (e.g., "8082" for dev, "80" for prod)
`mongo_uri`	MongoDB Atlas connection string
`env`	Environment: "development" or "production"
`session_secret`	Random string for session encryption

Note: Config files contain secrets and are excluded from git via .gitignore.

Usage

Accessing the Site

Public site: http://localhost:8082
Admin panel: http://localhost:8082/cm

First Login

Log in at /cm/login with your email and password. On first startup with an empty database, LightCMS creates an admin account from the LIGHTCMS_ADMIN_EMAIL environment variable (defaults to admin@localhost with password admin123). Change your password immediately after logging in.

To reset a password from the command line:

go run cmd/resetpw/main.go [email protected]

Creating Content

Log in to the admin panel at /cm
Go to Content → New Content
Select a template (Blog Post, Press Release, Explanatory Page, etc.)
Fill in the fields
Check "Published" and save

Managing Users (Admin Only)

Go to Users in the left sidebar (visible to admins only)
Create users with email, display name, and role (admin / editor / viewer)
Users receive a temporary password and are prompted to change it on first login
Disable accounts or reset passwords from the edit page
View a full audit trail of all user actions at Audit Log

Creating Custom Templates

Go to Templates → New Template
Define your fields (text, textarea, richtext, date, image, select)
Create an HTML layout using {{.field_name}} placeholders
Save the template

Available placeholders:

{{.title}} - Content title
{{.slug}} - URL slug
{{.published_at}} - Publication date
{{.your_field_name}} - Any custom field you define

Dynamic Index Pages: Tags, Snippets, and `lc:query`

LightCMS includes a system for building dynamic index pages that automatically update as you publish content. Three features work together: tags label individual pages, snippets define how each result is rendered, and lc:query directives embed live queries directly inside template layouts.

Snippets

A snippet is a named HTML template fragment stored in the CMS. When lc:query runs, it renders each matching content item through a snippet and concatenates the results.

Creating a snippet:

Go to Settings → Snippets in the admin panel
Click New Snippet, give it a name (e.g. glossary-pill)
Write HTML using Go template variables:

<a href="{{.FullPath}}">{{.Title}}</a>

Available variables inside a snippet:

Variable	Description
`{{.Title}}`	The content item's title
`{{.FullPath}}`	The public URL path (e.g. `/my-page`)
`{{.Slug}}`	URL slug only (e.g. `my-page`)
`{{.MetaDescription}}`	Meta description field
`{{.PublishedAt}}`	Publication timestamp

Example snippets:

A pill-style link (for glossary / tag cloud layouts):

<a href="{{.FullPath}}" class="pill">{{.Title}}</a>

A card with description:

<div class="card">
  <h3><a href="{{.FullPath}}">{{.Title}}</a></h3>
  <p>{{.MetaDescription}}</p>
</div>

A simple list item:

<li><a href="{{.FullPath}}">{{.Title}}</a></li>

`lc:query` Directives

An lc:query directive is an HTML comment you embed in a template layout. At page generation time — before the page is rendered — the CMS finds all matching content items, renders each one through the named snippet, and replaces the comment with the combined HTML.

Syntax:

<!-- lc:query filter="tag:TAGNAME" sort="title:asc" snippet="snippet-name" -->

Attributes:

Attribute	Required	Description
`filter`	Yes	Filter expression. Currently supports `tag:TAGNAME` to match content tagged with `TAGNAME`.
`sort`	No	Sort field and direction: `title:asc`, `title:desc`, `created_at:asc`, `created_at:desc`. Defaults to `title:asc`.
`snippet`	Yes	Name of the snippet to render each result through.

Example in a template layout:

<h2>AI & Machine Intelligence</h2>
<div class="links">
<!-- lc:query filter="tag:AI & Machine Intelligence" sort="title:asc" snippet="glossary-pill" -->
</div>

After the page is published, the directive is replaced with the rendered output of every published page tagged AI & Machine Intelligence, each passed through the glossary-pill snippet:

<h2>AI & Machine Intelligence</h2>
<div class="links">
<a href="/artificial-intelligence" class="pill">Artificial Intelligence</a>
<a href="/machine-learning" class="pill">Machine Learning</a>
<a href="/neural-networks" class="pill">Neural Networks</a>
</div>

Important: lc:query directives must be placed in the template's HTML layout field, not inside content data fields. The CMS processes them during page generation before Go's template engine runs (which would otherwise strip HTML comments).

Automatic Regeneration

Index pages that use lc:query are automatically regenerated whenever:

A tagged content item is published or updated
The template layout is changed
The snippet is updated
Regenerate All is triggered manually from the admin panel

This means you never need to manually rebuild your index pages — publish a new concept page tagged "Games & Interactive Experiences" and it appears in every index that queries for that tag within seconds.

Complete Walkthrough: Building a Tagging-Powered Index

Here's how to build a concepts glossary that automatically stays up to date.

Step 1: Tag your concept pages

For each concept page, add the appropriate tag in the content editor. You can use as many tags as you like, and the same content item can appear in multiple index sections.

Step 2: Create a snippet

In Settings → Snippets, create a snippet named glossary-pill:

<a href="{{.FullPath}}">{{.Title}}</a>

Step 3: Create a template with lc:query sections

Create a new template (e.g. "Concepts Index") with this HTML layout:

<article class="index-page">
  <h1>{{.title}}</h1>
  <div class="page-content">

    <h2>AI &amp; Machine Intelligence</h2>
    <div class="concept-links">
<!-- lc:query filter="tag:AI & Machine Intelligence" sort="title:asc" snippet="glossary-pill" -->
    </div>

    <h2>Games &amp; Interactive Experiences</h2>
    <div class="concept-links">
<!-- lc:query filter="tag:Games & Interactive Experiences" sort="title:asc" snippet="glossary-pill" -->
    </div>

    <h2>3D Graphics &amp; Rendering</h2>
    <div class="concept-links">
<!-- lc:query filter="tag:3D Graphics & Rendering" sort="title:asc" snippet="glossary-pill" -->
    </div>

  </div>
</article>

Note that {{.title}} is the Go template variable for the content item's title. Template variables use Go's {{.field}} syntax and are resolved after lc:query directives are expanded.

Step 4: Create and publish an index page

Create a new content item using your "Concepts Index" template. Give it a title and slug (e.g. /glossary). Publish it — the static page is generated with all the current tagged content already in place.

Step 5: Keep publishing

From now on, every time you create and publish a new concept page with a matching tag, all index pages that query for that tag are automatically regenerated and updated.

Template Variables

Beyond content data fields, templates have access to a few built-in variables:

Variable	Description
`{{.title}}`	The content item's title
`{{.slug}}`	URL slug
`{{.published_at}}`	Publication timestamp
`{{.your_field}}`	Any custom field defined in the template (richtext fields render as HTML)

Custom fields defined on your template are available directly by key. If you define a field with key intro, it's available as {{.intro}} in the layout. Richtext fields are automatically marked safe — their HTML is rendered as-is without escaping.

Content Authoring: Pre-Processing & Markup Features

LightCMS processes content field values before rendering them into your template. Authors can use the following markup features in any text or richtext data field.

Wikilinks

Link between pages using double-bracket syntax. Wikilinks are resolved at publish time and automatically kept up to date when a page's title or path changes.

Syntax	Result
`[[Page Title]]`	Link to a page matched by title (case-insensitive)
`[[Page Title\|display text]]`	Same, with custom link text
`[[/full/path]]`	Link to a page by its exact URL path
`[[/full/path\|display text]]`	Path link with custom link text

Broken links (no matching page found) render as <span class="broken-link">Page Title</span> so they are easy to identify and fix.

Snippet Includes

Embed a named snippet inline inside any content field:

[[include:snippet-name]]

The snippet-name must exactly match the Name field of a snippet in Settings → Snippets. Snippet includes are useful for reusable content blocks such as callouts, disclaimers, and calls to action that appear on many pages.

Place {{.lc_toc}} anywhere in your template's HTML layout to inject an auto-generated table of contents at that position:

<nav class="sidebar">
  {{.lc_toc}}
</nav>
<article>
  {{.body}}
</article>

At page generation time, LightCMS scans all headings in the final rendered HTML and outputs a <nav class="lc-toc"> block with anchor links to each one. Headings automatically receive id= attributes derived from their text content (see Heading IDs below), so the TOC links work without any extra setup.

Heading IDs

All headings (<h1> through <h6>) in rendered page output automatically receive id= attributes derived from their text. This enables deep-linking to specific sections.

Example:

<!-- In your content field -->
<h2>Getting Started</h2>

<!-- Rendered output -->
<h2 id="getting-started">Getting Started</h2>

The id is generated by lowercasing the text and replacing spaces and punctuation with hyphens. If two headings produce the same id, a numeric suffix is appended (getting-started-2, etc.).

Markdown Field Type

Template fields can be given the type markdown instead of text or richtext. Markdown fields support GitHub Flavored Markdown (GFM) including tables, strikethrough, task lists, and autolinks. The field value is converted to HTML at page generation time.

Markdown fields are a good choice for structured content that benefits from simple markup without a WYSIWYG editor — documentation pages, changelogs, FAQs, and similar content.

To create a Markdown field, set the field type to markdown when defining the template:

{ "name": "body", "label": "Body", "type": "markdown", "required": true }

Inline Tag Detection

Mention #tagname anywhere in a content field to automatically tag the page with that label. The tag is added to the page's tag list and participates in lc:query index pages just like manually applied tags.

Tag rules:

Must start with a letter
May contain letters, numbers, underscores, or hyphens
Example: This article covers #machine-learning and #ai adds both tags

This is a convenient alternative to editing the Tags field separately — useful when writing content in Markdown fields or richtext where you want to tag inline.

Creating Collections

Collections display grouped content (like a blog listing page).

Go to Collections → New Collection
Set the category filter to match your content's category
Define item and page templates
The collection will be available at /collection-slug

Customizing the Theme

Go to Theme in the admin panel
Adjust colors, fonts, and border radius
Add custom CSS if needed
Save to apply changes site-wide

End-User Search

LightCMS exposes a public search API at /api/search that your site's frontend can call.

Search API

GET /api/search?q=QUERY&mode=hybrid&limit=10

Parameter	Description
`q`	Search query (required)
`mode`	`hybrid` (default), `fulltext`, or `semantic`
`limit`	Max results 1–50 (default 10)

{
  "query": "game design",
  "mode": "hybrid",
  "total": 3,
  "results": [
    { "id": "...", "title": "Game Design", "full_path": "/concepts/game-design",
      "snippet": "...matching context...", "score": 0.97, "match_type": "both" }
  ]
}

match_type is exact, semantic, or both.

Typeahead Suggest API

GET /api/search/suggest?q=PREFIX&limit=8

Returns two lists for building a live typeahead dropdown:

{
  "keywords": ["game design", "game mechanics"],
  "pages":    [{"title": "About Jon Radoff", "path": "/about"}]
}

keywords — extracted from published content; clicking one triggers a full search
pages — direct-navigation results, ranked by: nav-linked → boosted-template → title-starts-with → title-contains → demoted paths

JavaScript Example

<input type="text" id="q" placeholder="Search..." autocomplete="off">
<ul id="suggest"></ul>
<div id="results"></div>

<script>
const input = document.getElementById('q');
const suggest = document.getElementById('suggest');
const results = document.getElementById('results');
let timer;

// Typeahead while typing
input.addEventListener('input', () => {
  clearTimeout(timer);
  const q = input.value.trim();
  if (q.length < 2) { suggest.innerHTML = ''; return; }
  timer = setTimeout(async () => {
    const r = await fetch('/api/search/suggest?q=' + encodeURIComponent(q) + '&limit=8');
    const d = await r.json();
    suggest.innerHTML = [
      ...(d.pages    || []).map(p => `<li><a href="${p.path}">📄 ${p.title}</a></li>`),
      ...(d.keywords || []).map(k => `<li><a onclick="doSearch('${k}')">🔍 ${k}</a></li>`),
    ].join('');
  }, 200);
});

// Full search on Enter
input.addEventListener('keydown', e => { if (e.key === 'Enter') doSearch(input.value); });

async function doSearch(q) {
  suggest.innerHTML = '';
  const r = await fetch('/api/search?q=' + encodeURIComponent(q) + '&mode=hybrid&limit=10');
  const d = await r.json();
  results.innerHTML = (d.results || [])
    .map(r => `<div><a href="${r.full_path}"><strong>${r.title}</strong></a><p>${r.snippet}</p></div>`)
    .join('') || '<p>No results.</p>';
}
</script>

Ranking Configuration

Ranking weights are configurable in the admin panel under Tools → End User Search → Search Ranking. Defaults: title-match boost 0.20, nav-page boost 0.15, concept-template boost 0.05, video-path penalty −0.05. Configure your Voyage AI key under Configuration to enable semantic search.

Project Structure

lightcms/
├── cmd/
│   ├── server/main.go        # HTTP server entry point
│   ├── mcp/main.go           # MCP server entry point
│   ├── cli/main.go           # CLI tool entry point
│   └── resetpw/main.go       # Password reset utility
├── config/
│   └── config.go             # Configuration loading
├── internal/
│   ├── apiclient/            # Reusable HTTP client for REST API
│   ├── auth/                 # Authentication, RBAC permissions, session management
│   ├── cli/                  # CLI subcommands and output formatting
│   ├── database/             # MongoDB connection & operations
│   ├── handlers/             # HTTP handlers (admin UI + REST API)
│   ├── mcp/                  # MCP server and tool definitions
│   ├── middleware/            # API auth middleware (API keys + OAuth)
│   ├── models/               # Data models & default templates
│   ├── oauth/                # OAuth 2.1 authorization server
│   └── services/             # Business logic (content, search, users, audit, etc.)
├── static/                   # CSS, JS, and uploaded files
├── content/                  # Custom pages and generated HTML
└── .goreleaser.yaml          # Release configuration

Default Templates

Blog Post

Fields: title, excerpt, featured_image, content, author, tags

Press Release

Fields: headline, subheadline, dateline, release_date, body, boilerplate, contact_info

Explanatory Page

Fields: title, subtitle, hero_image, intro, main_content, sidebar, cta_text, cta_link

Concept Page

Fields: title, definition, topic_links — ideal for wiki-style knowledge base entries

Standard Page, Blank Page, Homepage

General-purpose layouts for flexible content.

Multi-User Access Control

LightCMS v2.0+ supports multiple users with role-based permissions.

Roles

Role	Capabilities
admin	Full access: manage users, templates, theme, settings, audit log, all API keys
editor	Create/edit/delete/publish content; upload and delete assets; manage own API keys
viewer	Read-only access to content, templates, assets, and settings

Audit Log

Every mutation (content create/update/delete/publish, user management, settings changes, logins) is logged with the acting user's email, timestamp, and relevant details. Logs are retained for 365 days and accessible at /cm/audit.

API Key Permissions

API keys created by a user inherit that user's role. A key created by an editor cannot perform admin-only operations even if its token is shared. Admins can manage all keys; non-admins can only manage their own.

First-Time Migration

On first startup with an empty users collection, LightCMS automatically creates an admin user from the existing password hash in the database. Set the LIGHTCMS_ADMIN_EMAIL environment variable to specify which email address to use (defaults to admin@localhost).

API Keys

API keys are required for the REST API, MCP server, and CLI tool. Create them from the admin panel.

Log in at /cm
Go to Settings → API Keys
Click Create New Key, give it a name and descrip

Lightcms

README