Content Management
How to create, build and publish content using

Content Management

Content Management

This section describes how to use to create, build and publish content.

Overview is a file-based CMS, meaning that all content managed by a system is represented using files. This includes obvious things like HTML pages, images, stylesheets, JS files etc., but can also include data in the form of JSON files.

Because all content is represented using files, uses git to manage those files. Git is a natural choice to use with a file-based CMS. It provides all the tools needed to for adding and modifying files to a system; It provides a history of file changes, with the ability to undo changes or see when a change was made and by whom. and because it's the most commonly used version-control system, most developers are already familiar with it, and know how to use it. This means that unlike other headless CMSs, you don't need to learn an API from scratch in order to start interacting with - if you know basic git commands, then you already know everything you need to know about working with content in


The following diagram gives an overview of the content management lifecycle:

Content workflow

  1. Content is stored as files within a content repository. The master branch contains all used to generate the website or PWA hosted by the content repository - this includes HTML, markdown, images, stylesheets and JS files, as well as build configurations etc.
  2. The content repository is cloned to a developer's machine.
  3. The developer can then make changes to the repository, by adding, creating or editing files, and then adding them to the local copy of the repository.
  4. The developer then does a content build on their machine. This is normally done using's build tools. The build reads source content from the master branch and writes the build result to the public branch.
  5. The developer can then publish the build by pushing the contents of both branches back to the server.
  6. Once on the server, the published content can be accessed over the web via the content repository's public URL.
  7. When service workers are used to provide offline capabilities, then on clients that support them:
    • 7a. Once installed, the service worker will query the content repository for available content, which it will download and store in the local cache. When online, the service worker will periodically check the server for content updates, and download those when available.
    • 7b. Requests from the web page for content will then go through the service worker rather than directly to the content repository on the server.

Content repositories

A content repository in is a standard git repository that is used to store content. A single content repository is normally used to host a single website or PWA. However, it is possible to build websites or PWAs which combine content from multiple content repositories.

The content in a content repository is composed of both the published content and the source content that the published content has been generated from. In order to protect the source, and to provide a clear separation between source and public content, the two things are normally kept on separate branches of the same content repository. So source content is usually kept on the default master branch of the content repository, whilst the published content, generated from the source, is kept on a branch named public.

In this setup, only the contents of the public branch can be accessed over the public web. The contents of the master branch are considered private and cannot be loaded over the web.

In order to publish content, it needs to be put onto the public branch. This is normally done using's build tool, but can also be done via git, e.g. by adding content directly to the public branch, or merging from another branch.

The normal setup actually includes a third branch - named test - which as the name suggests, is used to test content before it is published. By default, build tools will read source content from master and write the build result to test, from where it can then be merged into the public branch once reviewed. This progression of content - from master to test and then to public is called the build workflow and is discussed in more detail later.

Public URLs

Every content repository has a unique public URL which allows content within that repository to be accessed over the web. For example, using the hosted server at, the standard public URL is formed by appending the domain name with the account name, prefixed with a tilde ~, followed by the content repository name.

For example, if the account name is "acme" and the content repository name is "products" then the public URL would be:

The public URL loads content from the public branch of the named content repository. Other public branches can be accessed by appending the branch name to the public URL. So for example, to access the test branch, append "test" to the URL:

The hosted server

A lot of the examples in this documentation use the hosted server as a convenient way to get a content repository up and running, but it should be possible to adapt the examples to run against a self-hosted server or a locally running content server.

Next steps

Read the following sections to learn more about content management in