pcms documentation
checkout the source

Table of contents

Quick start - for the impatient

This chapter guides you very quickly from installation to a fully-running site. For more information, please refer to the rest of the documentation.

Step 1 - get pcms

You only need a single pcms binary to run a website. Check out the sections below for a brief description how you get one.

As pre-built binary

You can download a pcms binary from a pre-built release from github:

https://github.com/bylexus/pcms/releases

Download and extract the pcms binary that fits your OS and architecture.

As go source code

You can build pcms from the go source code:

$ git clone https://github.com/bylexus/pcms.git
  • build it:
$ cd pcms
$ make build # ==> build goes to bin/pcms

Step 2 - init your project

pcms comes with a built-in starter template, which makes it easy to get started.

Open a terminal, and create a new pcms skeleton:

$ pcms init [project-path]
$ cd [project-path]
$ pcms serve

And done! Your site is serving on http://localhost:3000/!

Step 3 - Generate content!

The site skeleton is already up and running - now it’s time to look at the folder structure and implement some content.

After initializing a skeleton app with pcms init, you get the following file structure (content a bit redacted for brevity):

.
├── log
├── pcms-config.yaml        # The main configuration file. Adapt as needed
├── site                    # your site's source files
│   ├── index.html
│   ├── favicon.png
│   ├── html-page
│   │   ├── index.html
│   │   └── sunset.webp
│   ├── markdown-page
│   │   ├── index.md
│   │   └── sunset.webp
│   └── static
│       └── css
│           └── main.css
└── templates               # pongo2 templates for your html / markdown content
    ├── base.html
    ├── error.html
    └── markdown.html

Your page’s content goes to the site folder: This folder contains all your source files, markdown and html partials, static content and whatnot.

Inspect the folder structure to see how they work. It is really simple:

  • the main config file is pcms-config.yaml in the base directory. It stores all the important information to run your site.
  • The site/ folder contains your source files: html, markdown partials, static content etc. You mainly work in here to generate content.
    • index.html files are processed as pongo2 templates, and support a YAML frontmatter (see next chapter)
    • index.md files are processed as pongo2 templates, converted to .html and support a YAML frontmatter (see next chapter)
  • The templates/ folder contains your pongo2 base templates for your site, if needed

YAML front matter

index.html and index.md files support a YAML front matter to define template variables: See site/markdown-page/index.md as an example:

---
template: "markdown.html"
title: "Markdown sample page"
shortTitle: "Markdown"
iconCls: "fab fa-markdown"
mainClass: "markdown"
metaTags:
  - name: "keywords"
    content": "pcms,cms"
  - name: "description"
    content": "Markdown sample page"
---
# Markdown Demo Page

[<i class="fas fa-home"></i> Back to home](/)

Your actual Route: /quickstart/index.html

Access to pongo2 syntax, e.g. actual time: 11.04.2026 14:57:39

Use an icon: <i class=""></i>

The YAML front matter is the start part beteween the --- separators, and (may) contain valid YAML content. This content then will become available in your pongo2 templates via the Page.Metadata object. For Markdown files, the only needed entry is template:, which defines the HTML template to be used from the templates/ folder to generate the final HTML.

Step 4: Index and serve

pcms index builds the sqlite-based page index. Issue this if any of your page contents change to update the page index.

pcms serve starts the web server and processes your page files and other static content.

Step 5: … and beyond!

Please have a look at the other chapters for a more detailed description on how to configure and use pcms.

top