Skip to content

Instantly share code, notes, and snippets.

Last active September 6, 2020 03:36
Show Gist options
  • Save thomasdavis/db7db8d07ccb086504261802edf3069a to your computer and use it in GitHub Desktop.
Save thomasdavis/db7db8d07ccb086504261802edf3069a to your computer and use it in GitHub Desktop.

Introducing JSON Blog

dcwr (don't care, won't read) This project aims to make your entire blog contained in a single file (content sourced from where ever you want), of which you can do what ever you want via utilizing tools built in a community fashion.

Getting Started

mkdir myblog && cd myblog
npm i -g jsonblog-cli
blog init
blog build
blog serve


I feel like I don't speak just for myself but over the years maintaining a blog has been rather arduous. I hate setting them up, I suck at keeping them alive, I dislike buying into platforms, I cannot seem to back them up and they are always way more than I actually needed.

Just recently I happened to stumble upon a Hacker News comment by Jedberg where he also listed his pain points with personal blogging which largely mirroed my own gripes. His comment and seeing the other trends wishing to relive the personal blogging era compelled me to attempt something.

Some readers might have realized already, but JSON Blog was inspired by another project that I co-founded a few years ago called JSON Resume. Essentially your resume is defined as formatted data which you are free to take anywhere you want and use community built tooling to analyze, render and host.

JSON Blog is at core a schematic simply to describe a blog, and I've spent some time developing some initial tooling to make it rather seamless to get started. Here is a simple example (that generates this site)

  "site": {
    "title": "My Blog",
    "description": "I write my thoughts here"
  "basics": {
    "name": "Thomas Davis"
  "posts": [
      "title": "Introducing JSON Blog",
      "source": ""
  "pages": [
      "title": "About",
      "source": ""

As with any schema, you might say that the naming conventions are terrible, and I'd agree. The reasoning behind any individual semantic choices might be rather complex so I can just tell you by what principles I chose these initial ones.

First, once you add anything to a schema, it cannot be removed without difficulty from the ecosystem. So I've only started with the bare essentials. There are some obvious additions to be made such as tags and categories but I've yet to define them for the second reason.

Schema's are only valubable in so far as person's will agree with them. (all reality is just consensus anyway jks). The success of a schema is dependent on if it is agreeable or not, therefore you need to have a bunch of differing opinions. So there is a schema repo, where anyone can chime in and some people will be elevated to arbiters. And those who debate will complain about lack of change, can't blame them, but change should be slow. And I won't pretend, that Me, the programmatic surgeon dictator won't have a final say. All I can say on that is that I've been consistenly wrong and;

We have two ears and one mouth so that we can listen twice as much as we speak - Epictetus


The tools I've built are Javascript only but as a schematic the language of tooling is agnostic.

source in the schema is meant to promote that a blog shouldn't care where you host your content, just make it a publically accessible URI, of which plenty of servies support Drive, Dropbox, Gist, pastbin

Essentially implying you can pass your blog.json to any function/company and they should be able to construct it. Which leads onto the concept of a generator;


A generator so far envisioned is a function that simply takes a blog.json and outputs an array of files and their content e.g.

  "files": [
      "name": "index.html",
      "content": "<h1>I am a good person</h1>"
      "name": "assets/logo.svg",
      "content": "<svg version=\"1.1\"><text>Hello noob</text></svg>"

The generator should then loop through the files, create directories and files where necessary and pipe in the content.

You can read more about generators at

This entire project is still under development, but looking for feedback because I can't tell if it is a good idea.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment