Static Blogs with Keystone

This is a starter template to build statically generated blog-like websites with Keystone and Next.js. The template is built with and styled using Tailwind's configuration based theme which makes it easy to extend and customise it.

Check it out here — Static Blogs with Keystone.

How does it work?

The short version is that the blog is entirely generated during build-time using Next.js static site generation and the content for the blog is made available during build-time using Keystone's powerful content platform along with the magic of zero configuration file-system based SQLite database.

The blog is generated statically using Next.js static HTML export.
The content for the blog is fetched from a local Keystone server. Keystone is a fantastic content platform that auto-magically generates GraphQL API based on schema definitions.
Usually content platforms need to be connected to a database and hosted somewhere which often comes with hosting, configuration and maintenance cost. Keystone supports SQLite database and we make use of that to avoid having to configure, host or maintain anything. You can get started with zero configuration and commit your database along with your code like any other file. 🤯 This is what makes this whole generate blogs locally without having to host a server anywhere possible.
Author your content visually in your local environment using Keystone's powerful document editor and admin dashboard. Once your content is ready, just run a local build and your blog will be exported as a static website. Now you can easily host this static website anywhere. I created my blog using this template and hosted it in Netlify. Every time I make a change to my content, all I gotta do is push my changes to the repo and Netlify automatically deploys it in less than a minute.
The generated blog and content is styled using Tailwind and could be easily customised easily.

How is this different from mdx based blogs?

The idea is same - you statically generate your blog using content made available during build-time. The difference however, is that, MDX authored content is passed through a plugin system during the build and the content is made available in your pages to be built. This is easy as long as you only need the default out-of-the-box markdown syntax content. The moment you want to customise your content with fancier components (Eg. carousel, YouTube video, Twitter embed, syntax highlighted code, Hero image, etc) you will either have to find a plugin that supports that or build them yourself which sometimes can get quite cumbersome.

This is where Keystone's all powerful document field comes into play. You can author content using a visual editor and see how your content is going to look while authoring it. And most importantly Keystone's document field makes it easy to add custom components (Eg. carousel, YouTube video, Twitter embed, syntax highlighted code, Hero image, etc). All you need to know to add a custom component is to know how to code in React and voila. 🥳 This template is setup with a few custom components (hero image, custom blockquote, embed tweet, embed youtube videos, callouts and syntax highlighted code blocks). You can see them in action here — Keystone Content Authoring Experience is Just Fantastic!.

Keystone's document editor stands out in a handful of ways over MDX based content —

Ability to visually see your content while authoring it.
Keystone's admin dashboard makes it easy to publish/unpublish content, go through all your content visually for editing, author SEO information along with your post, etc.
Complete control over how you render and style your content. Default out-of-the-box elements and your custom elements can be styled however you want.
Multi-column layouts for your content.
And more. Keystone's document editor is friggin' fantastic.

Getting started

The project is a monorepo with Keystone server in keystone-server workspace and the next frontend in next-app workspace.

yarn at project root installs the dependencies for both the server and the frontend app.
yarn dev at project root starts the Keystone server at http://localhost:3000 and the next app at http://localhost:8000

You can alternatively open two terminal tabs and run yarn dev individually within keystone-server and next-app directories.

Authoring content

Open your keystone admin dashboard locally at http://localhost:3000 and start authoring content.

If you want to create a new blog post, you can create one in Posts.
If you want to link to an external blog post or a link you can create one in Links.

Generating blog

Once your content is ready, keep the keystone server running and open the Next.js app at http://localhost:8000.

Generate your blog by running yarn export. This will export your website in next-app/out directory.
You can check out your generated content locally by running yarn serve in next-app dir.

Deploying

The generated website is just a bunch of html, js and css files. You can host it where ever you want. You can choose one of these three methods to deploy.

1. Build in local and push the built files to your repo

You can run yarn export in your local environment and it will export the static website to next-app/out dir. You can just commit these static files and ask your CI to deploy these files. Eg. If you're using Netlify, you'll tell Netlify that just publish the files in next-app/out dir on every new commit to the repo. Check netlify.toml file for more info on how to do it.

2. Build in CI

You can choose to automate your deploy process by building your website in a CI. There's a limitation with this though. During build, the content is fetched from a running local keystone server. Not all static hosting CI's support running a local server. So the build process needs to be dockerised. You will need to run yarn export:docker to build your website in a docker environment. But remember not all CIs support docker either. So if your CI supports docker, you can just run yarn export:docker in your CI and the site will be exported at next-app/out dir. If your CI doesn't support docker (like Netlify where this template is hosted) you could use GitHub Actions to build your website in GitHub's CI and publish it to your hosting using their CLI. Eg. This template is hosted in Netlify, so there's a GitHub action at .github/workflows/build-and-release.yml that builds the website on every push to main and deploys to Netlify using Netlify's CLI.

Where do I deploy?

The generated website is just a bunch of html, js and css files. You can host it where ever you want. Here are a few options that will automatically deploy the website as soon as you push the generated files to your repo.

brandon-v-seeters/keystone-static-blog