💪 Static sites with superpowers
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Eduardo Bouças 2bc26420d3 Merge pull request #137 from tbodt/patch-2 4 years ago
controllers Add StandardJS 5 years ago
coverage Add date: placeholders 5 years ago
docs Update README 5 years ago
lib Merge pull request #119 from eduardoboucas/dev 5 years ago
test Add date: placeholders 5 years ago
.dockerignore Docker config added. 5 years ago
.env .env cleaned up 5 years ago
.gitignore Environment based configs ignored in .gitignore. 5 years ago
.travis.yml Remove Travis email notifications 5 years ago
CONTRIBUTING.md Add StandardJS 5 years ago
Dockerfile Docker config added. 5 years ago
LICENSE.md Add license 5 years ago
README.md Update README.md 5 years ago
config.js Add StandardJS 5 years ago
config.sample.json Add sample config file 5 years ago
config.test.json Add StandardJS 5 years ago
docker-compose.development.yml ReCAPTCHA enabler flag moved to SiteConfig 5 years ago
docker-compose.yml coxker-compose.yml template updates 5 years ago
index.js Add new entry point file 5 years ago
logo.png Update logo image 5 years ago
package.json Upgrade js-yaml to 3.10.0 4 years ago
server.js Add StandardJS 5 years ago
siteConfig.js Add extension property to site config 5 years ago
staticman.sample.yml Remove remaining traces of allowedOrigins 5 years ago
staticman_key.pub Add public key 5 years ago


Staticman coverage Build Status JavaScript Style Guide

Static sites with superpowers


Staticman is a Node.js application that receives user-generated content and uploads it as data files to a GitHub repository. In practice, this allows you to have dynamic content (e.g. blog post comments) as part of a fully static website, as long as your site automatically deploys on every push to GitHub, as seen on GitHub Pages, Netlify and others.

It consists of a small web service that handles the POST requests from your forms, runs various forms of validation and manipulation defined by you and finally pushes them to your repository as data files. You can choose to enable moderation, which means files will be pushed to a separate branch and a pull request will be created for your approval, or disable it completely, meaning that files will be pushed to the main branch automatically.

You can download and run the Staticman API on your own infrastructure, or you can simply use the public instance of the Staticman API for free. If using the public instance, you can skip to Setting up repository.


  • Node.js 4.8.3+
  • npm
  • A personal access token for the GitHub account you want to run Staticman with
  • An SSH key (click here to learn how to create one)

Setting up the server

  • Clone the repository and install the dependencies via npm.
  git clone git@github.com:eduardoboucas/staticman.git
  cd staticman
  npm install
  • Create a development config file from the sample file.
  cp config.sample.json config.development.json
  • Edit the newly-created config file with your GitHub access token, SSH private key and the port to run the server. Click here for the list of available configuration parameters.

  • Start the server.

  npm start

Each environment, determined by the NODE_ENV environment variable, requires its own configuration file. When you’re ready to push your Staticman API live, create a config.production.json file before deploying.

Check this guide if you’re using Docker.

Setting up a repository

Staticman runs as a bot using a GitHub account, as opposed to accessing your account using the traditional OAuth flow. This means that you can give it access to just the repositories you’re planning on using it on, instead of exposing all your repositories.

To add Staticman to a repository, you need to add the bot as a collaborator with write access to the repository and ask the bot to accept the invite by firing a GET request to this URL:


If you’re using the public instance, the account you want to add is staticmanapp and the URL is https://api.staticman.net/v2/connect/GITHUB-USERNAME/GITHUB-REPOSITORY.

Site configuration

Staticman will look for a config file. For the deprecated v1 endpoints, this is a _config.yml with a staticman property inside; for v2 endpoints, Staticman looks for a staticman.yml file at the root of the repository.

For a list of available configuration parameters, please refer to the documentation page.


Would you like to contribute to Staticman? That’s great! Here’s how:

  1. Read the contributing guidelines
  2. Pull the repository and start hacking
  3. Make sure tests are passing by running npm test
  4. Send a pull request and celebrate

Sites using Staticman

Are you using Staticman? Let us know!