Xiaoxing's Notes

Building a Website with org-mode Files

November 23, 2020
742 words
3 minutes

🌲 Ever Growing List of Tips

Keep an eye on this list, it's growing.

org-mode export function is great, but simple html + css is not going to cut it any more. To create a modern website using your org files, with gatsby as the backbone, simply do this:

npm install -g gatsby-cli
gatsby new my-website https://github.com/orgapp/gatsby-starter-blorg

It's one command away from getting it running locally. You will have a powerful website sitting on localhost:8000 afterwards. Which conveniently, also is a complete documentation of the tool.

cd gatsby-site # if you haven't already
npm run develop

What's in the Box

You get all the benefits from gatsbyjs, the flagship tool for creating modern websites. It will net a pretty good score on Google's website evaluation tests.

Google web.dev score of the starter project

Here is a list of the important (in my opinion) features you get right away.

Optimised for SEO

You get detailed metadata for every page. They came from your org file itself (properties, tags, description etc...). Open up inspector of this page, and you will see something like this:


Some of them will help boost your website visibility on the internet. The Twitter ones will make your pages look amazing when shared on Twitter.

tweet card preview

Responsive Design

Over time, more people will be reading your words on their tiny smartphone screens instead of a glorious 4K display like yours. Resize the window to see how it transforms into a different layout gracefully.

Progressive Web App (PWA)

I don't need my website to be as sophisticated as an app, but it is nice to add additional resistance to a bad network to it. Your website will pre-fetch content and cache it in the browser like an app. So the whole website works 100% even when your device is offline. Also clicking an internal link feels like pressing a button on an app.

Blazing Fast

Gatsby is fantastic when it comes to optimising your website for the modern internet. All the files are small and split in logical ways to minimise traffic required to open your website. Believe it or not, even though the whole thing is written in JavaScript and React, your website can render correctly with JavaScript turned off[1]. Everything is rendered at build time.

Dark Mode

Colour is a personal thing. The point is, you can customise every single detail about them, and you get two sets of them.

light/dark mode side by side

Highly Customisable

Every bit of the website is customisable. From the header to footer, from the post layout to the date and tags. If you'd like, you can nuke everything and build them from scratch.

Designed with org-mode user in mind

In some sense, org-mode is similar to markdown. But it's so much more flexible. So people use it in all kinds of ways. The following features are tailored particularly for org-mode users.

  • Not everyone likes to write their stories on a per-file basis, so you can publish posts at both headline level and/or file level.
  • Instead of massive configuration options in a JSON file, the configuration stays in your org files via In-Buffer Settings and Properties wherever possible.

What's the Catch

  • You going to have to be okay with the fact that it's written in JavaScript.
  • It is react based, so if you want to go deep in the customisation game, you going to have to be comfortable with copy & pasting, maybe tweaking some jsx or tsx files.

Getting Started

Why reinventing wheels over and over when you can stand on the shoulders of the giants and just benefit from others' struggles? Obviously, the giants here are the open-source communities. That's the reason I built the org-mode parser orgajs in JavaScript (TypeScript actually) in the first place, to integrate with the mass. With a couple of simple plugins, it works seamlessly with a well-established ecosystem (namely gatsbyjs). I am taking massive advantage of other people's work, and it goes along with the evolution of the ecosystem. I know us geeks won't ever be satisfied on pre-made stuff. That's why I create multiple levels of customisation points in the tool (articles coming later). If you have any issue or suggestions for the project, you can create issues. Or talk to me on Twitter directly. I would love to know your thoughts. If you are ready to Get Started, do so.


You do need JavaScript turned on when you want more dynamic pages that, for example, does data fetching at render time. Of cause you don't need any of that for your blog post pages since they are pre-rendered at build time.

Read more stories about "emacs" ->