# cState: a static status page built with Hugo, and what it does not monitor

> cState is a Hugo theme and example site that turns Markdown incident files into a fast, hostable status page. It records incidents well, but it does not watch your services for you.

**cstate/cstate** — 🔥 Open source static (serverless) status page. Uses hyperfast Go & Hugo, minimal HTML/CSS/JS, customizable, outstanding browser support (IE8+), preloaded CMS, read-only API, badges & more.

- Repository: https://github.com/cstate/cstate
- Website: https://cstate.uncascade.com/
- Stars: 2,896 · Forks: 250
- Language: HTML
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/cstate-cstate

## The problem cState solves, and the problem it deliberately leaves alone

Most status pages are dashboards wired to a monitoring agent. cState is the opposite: it is a publishing format. You write an incident as a file, commit it, and a Hugo build turns it into a page. The README describes the project as a "static (serverless) status page" and calls the result an "informational hub". That framing is honest about the trade-off. Because the output is static, there is no server process to poll your endpoints, and the README states directly that cState "cannot do automatic monitoring out of the box", linking to an issue thread on the subject.

The audience is therefore narrower than the tagline suggests. It fits teams that already know when something broke, usually because a monitor or an on-call human told them, and who now need a public record of what happened and how long it lasted. It also fits organisations with legacy browser requirements: the README claims support back to Internet Explorer 8, and the JavaScript on the page is described as an enhancement rather than a requirement for seeing the vital information. If your users are on locked-down corporate desktops, that claim is worth more than any feature list.

What it does not fit is a team that wants the status page itself to be the detector. The README is explicit that commercial options "may update faster because of their architecture, have built-in real-time uptime monitoring, send notifications by email or other means", and that cState is not trying to beat them. Read that as a scope statement, not modesty.

## How a cState site is assembled: Hugo theme, Markdown incidents, static output

The repository layout makes the architecture visible. There is no application server. The top level holds layouts/, static/, i18n/, archetypes/ and a theme.toml, which is the shape of a Hugo theme, plus an exampleSite/ directory that acts as the starting point for users. The README says as much: to Hugo, "cState acts like a theme".

So the data flow runs in one direction. Incident entries live as content files. Hugo reads them along with the theme's layouts and the i18n translation files, and emits a static site into public/. The README notes that incidents can be linked to systems or categories, that previous downtime durations are surfaced, and that statistical calculations show takeaways such as time spent fixing an issue. All of that is computed at build time from the entries, not at request time.

The build itself is the part cState leans on hardest. Hugo is written in Go, and the README claims it "can build a site with thousands of entries in seconds". That matters for a status page with years of history, because every incident ever published is re-rendered on every deploy. The Dockerfile in the repository reflects the same model: it starts from nginx:alpine, installs hugo and git with apk, copies exampleSite into /cstate, copies the repository into /cstate/themes/cstate, and drops an entrypoint script at /docker-entrypoint.d/10-build-hugo.sh so the site is rebuilt each time the container cold-starts.

Outputs beyond HTML are part of the design. The README lists RSS, a read-only API, and badges in the style of shields.io, plus a separate project, cstate/html-embed, that adds a dot indicator or an alert when the status page has active issues. Those are the integration points: you do not query cState, you consume files it already generated.

## Installing cState and publishing your first incident

The README is clear that this is the user path, not the contributor path, and that what you are creating is "a Hugo site with specific, already existing modifications". You do not install cState as a package. You clone or generate from the example repository, then point a static host at it.

The first step is generating your own copy of the example site. On GitHub this is done from the cstate/example repository using the template button, which the README links to as "generate". Once you have that repository, the platform settings are the same almost everywhere: the build command is hugo, the publish directory is public, and you must supply a Hugo version. The README gives 0.101.0 as the value for the HUGO_VERSION build environment variable, noting "or later".

For Cloudflare Pages specifically, the README lists these settings after you create a new site from Git:

```text
Build command: hugo
Publish directory: public
HUGO_VERSION = 0.101.0
```

Netlify is the shortest route if you also want Netlify CMS, because the README says the CMS "works best with Netlify" and offers a deploy button that starts from https://github.com/cstate/example. After the first deployment, you should see the example status page rendered at your host's URL, with the sample incidents from exampleSite in place.

If you prefer to run it yourself, the repository ships a Dockerfile that builds the site with Hugo and serves the result through nginx. The image copies exampleSite as the working site and the repository itself into themes/cstate, and the entrypoint script rebuilds the site on each cold start. That means content changes require a new container start, not a file edit on a running server, because there is nothing watching the content directory.

From there, publishing an incident means adding a content file and committing it. The README points to the command line or to a Git-based CMS such as Netlify CMS or Forestry for a no-code experience, and to jamstack.org for other Git-based CMS options. Whichever route you take, the deploy pipeline rebuilds public/ and the incident appears.

## Where cState is the wrong tool

The largest limitation is stated by the project itself: no automatic monitoring. If your requirement is that the status page turns red within seconds of an endpoint failing, cState cannot satisfy it without you building the detection layer separately and writing the incident yourself. The README's suggested pattern is exactly that inversion: record incidents, because "most of the time your services are functioning, so the status page does not need to be updated".

There is a second, quieter constraint in the build model. Because incidents are content files rendered at build time, correcting a typo or adding a postmortem means a new commit and a new deploy. On a platform with a build queue, that is a latency you do not control. The README's GitLab Pages note is a concrete example: support there is described as experimental, and the README warns it "may take up to 30 minutes before the site is available after the first deployment". That is a deployment characteristic of the host, and it is the kind of thing that matters during an incident when you want the page updated now.

GitLab Pages is also flagged as "a relatively untested option" in the README at the time that section was written. Treat the platform list as a ranking of confidence rather than a list of equals: Cloudflare Pages is recommended for larger teams, Netlify for the easiest setup, and the rest are options with varying levels of documentation behind them.

Finally, the browser support claim and the no-JavaScript design are only advantages if you need them. If your audience is on modern browsers and you want live-updating components, you are paying for compatibility you will not use.

## cState against a hosted status service

The natural alternative is a commercial status page product, and the README names the difference in approach rather than a specific competitor: those services update faster because of their architecture, include real-time uptime monitoring, and send notifications by email or other means. In practice that means a hosted service owns the whole loop. Its agents probe your endpoints, open an incident automatically, notify subscribers, and update the page without a commit. You get less control over markup and you depend on a vendor's infrastructure being up when yours is not.

cState inverts every one of those properties. You own the content and the build, the page is a set of static files, and there is no vendor in the request path. The cost is that the loop is manual. You supply the monitoring and the notification, and you supply the incident text.

A second comparison is closer to home: cState is a Hugo theme, so any other static site generator plus a hand-written incident template is technically an alternative. What cState adds over that is the parts you would otherwise build yourself: the incident and system content model, the i18n files for the languages the README lists (English, German, French, Italian, Lithuanian, Macedonian, Dutch, Portuguese, Turkish and Tagalog), the read-only API and badge outputs, and the Netlify CMS configuration. If you only need a single page with a coloured dot, a hand-rolled Hugo or Jekyll site is less machinery. If you need incident history with durations and per-system attribution, cState already has the schema.

## Upgrades, maintenance and the MIT licence

The last push to the repository was on 2026-08-27, and the most recent release listed is 6.0.1 from 2025-07-30, a bug-fix release following 6.0.0 in March 2025. There is no archive flag on the repository. The practical upgrade question for a static theme is whether your content files and configuration survive a theme change, and the release history shows at least one large version jump, v6.0.0, described in its own title as a "HUGE Update". Anyone running a v5 site should expect to read the release notes before moving, because a theme upgrade can change layouts and configuration keys rather than just fix bugs.

The other upgrade surface is Hugo itself. The README pins HUGO_VERSION to 0.101.0 or later for the Cloudflare Pages build, so a site that has been running for a while may be building on an older Hugo than a fresh install would pick up. Since the theme and the generator version move independently, a Hugo bump is a separate change from a cState bump, and the two should not be tested together if you can avoid it.

On licensing, cState is MIT licensed, per the LICENSE.md file in the repository root. MIT is permissive: it allows commercial use, modification and redistribution, and it requires that the copyright notice and permission notice be included. That is a summary of the licence text, not legal advice, and the usual caveat applies: if you redistribute cState as part of a product, read LICENSE.md yourself. Note also that the README solicits sponsorship for the maintainer, which is separate from the licence and imposes no obligation on users.

## Conclusion

Adopt cState if you want incident history published as static files, you are comfortable editing Markdown or wiring up a Git-based CMS, and you accept that detection is somebody else's job. Do not adopt it expecting built-in uptime checks, alerting or email notifications; the README says plainly that it cannot do automatic monitoring out of the box. Before you commit, verify three things: that the Hugo version you pin is at least 0.101.0, that your chosen host's build command is hugo with public as the publish directory, and that the read-only API and badges expose the fields your own dashboard needs.

## FAQ

### Does cState monitor my services automatically?

No. The README states that cState cannot do automatic monitoring out of the box and links to an issue thread on the subject, describing the page as an informational hub instead. Because the output is static, it cannot poll services in real time; you record incidents yourself.

### What do I need to install to run cState?

You do not install cState as a package. You generate a repository from cstate/example, then configure a static host with the build command hugo, the publish directory public, and a HUGO_VERSION build environment variable set to 0.101.0 or later.

### Which hosting platforms does cState work with?

The README lists Cloudflare Pages as recommended for larger teams, Netlify as recommended for most easy setup, and GitHub Pages, GitLab Pages, Vercel, render.com or self-hosting as further options. GitLab Pages support is described as experimental and relatively untested.

### Can I use cState without editing files in Git?

Yes, if you attach a Git-based CMS. The README points to Netlify CMS, which it says works best with Netlify, and to Forestry.io, or you can use your Git provider's online editor.

### What outputs does cState produce besides the HTML page?

The README lists RSS, a read-only API, and badges similar to shields.io, and points to the separate cstate/html-embed project for a dot indicator or an alert when there are active issues.

## Sources

- [cstate/cstate on GitHub](https://github.com/cstate/cstate)
- [License: MIT](https://github.com/cstate/cstate/blob/master/LICENSE)
- [Project website](https://cstate.uncascade.com/)
- [README](https://github.com/cstate/cstate/blob/master/README.md)
- [Releases](https://github.com/cstate/cstate/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cstate-cstate