A simple static site generator with deployment to S3/Cloudfront.
Stasis is a static website generator written in Python, using Pandoc to convert Markdown documents to html rendered with Jinja2 templates, and optionally deploying to Amazon S3 and Cloudfront.
Stasis is designed to mimic the workflow offered by Jekyll and is mainly targeted at personal blogs. The feature set is quite basic, but this also makes the program easy to understand and extend to fit your needs.
- Conversion of Markdown posts to html, with Pandoc extensions available at your discretion.
- Workflow similar to Jekyll: init, clean, build, serve, deploy.
- Easy to use templates with Jinja2.
- A basic development server for previewing the site locally.
- Index pages with pagination.
- Static or "flat" pages, also written in Markdown and rendered to a specified url (eg. about, contact, 404).
- A sidebar with links, recent posts, and topics.
- Topic pages.
- RSS feed generation.
- Deployment to S3 with dry-run, ignore on server, exclude from upload, and Cloudfront invalidation.
- Purely static html output.
For more detail and background, please see my blog post about why I wrote Stasis.
First, install Pandoc following the documentation for your system.
To install the latest distribution of Stasis from PyPI, install using pip. The install will create a console script called
stasis, so I recommend doing this within a virtual environment.
pip install stasis-ssg
Alternatively, for the latest source code, clone this repository first and then install the package from a local working directory, for example:
mkdir stasis-devel && cd $_ mkdir .venv python3 -m venv .venv/stasis source .venv/stasis/bin/activate git clone https://github.com/czep/stasis.git . pip install -e .
stasis -v to verify that the install worked.
After installation, create a new working directory in which to develop your site. Make sure this is a new empty directory:
mkdir ~/mysite && cd $_ stasis init
init command will create a basic starter site in the current directory. The default setup will look like this:
├── _pub # target location for building the site and staging for deployment ├── drafts # optional drafts folder ├── pages # static pages ├── posts # markdown posts ├── stasis_config.py # configuration options ├── static # files to be copied directly to _pub └── templates # Jinja2 templates
After initializing the site, the next steps are:
stasis_config.pyto customize your site's metadata and other configuration options.
- Edit the templates to get the layout you want.
- Copy your CSS file to
static/css/main.css. Add any additional static files to the
staticdirectory. These will be copied to
_pubwithout being processed.
- Add static pages to the
- Add posts to the
These commands will help you build and deploy your site:
stasis build stasis clean stasis build --target=prod stasis serve stasis deploy --dry-run CLOUDFRONT_ID=EXXXXXXXXXXXXX stasis deploy
stasis build alone or with the development target
stasis build --target=dev will generate the site with relative links. Internal
<img> tags will begin with
/. This makes it easier to navigate through the site when serving it locally. Building with the production target
stasis build --target=prod will prepend the site's baseurl defined in
stasis_config.py to all links, making them absolute instead of relative. This is likely what you will want to do before deployment to ensure that all of your links point to their respective canonical pages.
To build the site with drafts enabled, run:
stasis build --drafts
At any point if you want to do a fresh rebuild, run
stasis clean. This will delete everything in
_pub as well as the cached posts in
Start a very simple web server to preview your site. Unlike in Jekyll, there is not an option to serve the site with or without drafts. The server will simply show you whatever has been built in the
Before trying to deploy, change the
S3_BUCKET config options. I recommend creating a new profile that has S3 Read/Write permission as well as permission to invalidate your Cloudfront distribution. Add this profile to your
The first time you try to deploy, please do so with the
--dry-run argument to make sure the the results are what you expect. Dry run will connect to your S3 bucket, compare local and remote files, and print an output containing three sections:
- New files to upload to S3
- Modified files to upload to S3
- Old files to delete from S3
Examine the list before running without the dry-run option. In
stasis_config.py, there are two pattern lists that can help control what is and is not deployed:
IGNORE_ON_SERVER specifies patterns that will not be added, modified, or deleted. Use this for any legacy content that you want to manage manually.
EXCLUDE_FROM_UPLOAD specifies patterns that will not be uploaded to S3 from your local filesystem.
By default, stasis will compress most text files before uploading. This can be toggled with the
S3_USE_GZIP config option. If True, for all files that meet the gzip criteria, a copy will be created with an extension of ".upload". This is simply a gzipped copy of the original file and is only used during the deployment process. However, you must keep the pattern
EXCLUDE_FROM_UPLOAD to prevent these files from also being uploaded.
When ready to deploy, pass your cloudfront distribution ID as an environment variable:
CLOUDFRONT_ID=EXXXXXXXXXXXXX stasis deploy
After deploying to S3, this will start a root-level wild-card invalidation
'/*'. If you do not want stasis to do the invalidation for you, or if you are not using Cloudfront at all, simply run:
This will deploy to S3 but will not attempt a Cloudfront invalidation.