Xiaoxing's Notes

Build Modern Website with org-mode and Gatsby (Basic)

Gatsby is an awesome modern website builder. It is one of the top ones according to this website.Org-mode is, in my own opinion, the best plain text system that strikes the perfect balance (again, to me) between simplicity and versatility. I feel the urge to combine these two. And here you go.

You need nodejs installed in your system for this solution to work.

Quick Start

We are going to use a gatsby starter template designed with org-mode support in mind. I have done all the heavy lifting (and keep it working) so you don't need to.

Get gatsby CLI.

npm install -g gatsby-cli

Create a new website with a starter template with org-mode support.

gatsby new my-org-website https://github.com/orgapp/gatsby-starter-orga

Get it going in your browser.

cd my-org-website/
npm run develop

Your site is now running at http://localhost:8000! It looks very basic because it's up to you to make it your own.

How Does it Work

Gatsby is a static website generator. So basically it takes a bunch of files as input and spit out a website as an output. In this case, the input is mostly your org files. By default they are in a folder called content under the root of the project. It should contain some example files to show you how it works. But it can be changed in gatsby-config.js using the contentPath option. Relative path is supported. E.g. ../notes/.

There are two ways for it to recognize your content as a post.

  • Standalone org files with a title.
  • Sections with keyword that matches ORGA_PUBLISH_KEYWORD in buffer setting.

Take a look at the dummy content for details.

Oh, it generates index pages too. Again see the documentation for details.


Open up gatsby-config.js and take a look at the plugins section. It should be pretty self-explanatory with the comments. I don't want to put too much technical details here because they don't age well. Use the README.md file as the definitive source of documentation.