Before using any of the examples, you have to build the monorepo.

git clone git@github.com:orgapp/orgajs.git
cd orgajs
yarn
yarn build

Now you can cd into specific example project directory and start hacking.

You should choose…

gatsby

if you use gatsby, want highly customized website, render react component directly in org file. okay with one page per org file.

gatsby-posts

if you use gatsby, want out-of-the-box blog-like website. Organize posts into either files or sections in files. Mostly okay with the default layout.

gatsby-posts-core

if you want to customize gatsby-posts to the bone.

next

if you use next.js

webpack

if you want total control, build from scratch, use webpack

If you are trying to choose a gatsby example, here are some technical details that you should know. There are currently two styles of rendering org-mode content in gatsby.

This is the original implementation. To draw parity from the markdown world, the implementation is similar to gatsby-transformer-remark. It’s a gatsby “transfomer” plugin. To summaries, it taps into gatsby’s build lifecycle and transform source (your org files in this case) into gatsby nodes, eventually render them as web pages. You will get custom graphql types (OrgContent, if use the gatsby-theme-posts-core or gatsby-theme-posts, it gets translated into OrgPost type). So you can generate your own custom pages, like a post list page, with the help of graphql queries. Another special feature is the ability to generate multiple pages from sections within single org-mode file. Basically your org-mode files are treated as data. Take a look at the following examples for details.

• gatsby-posts
• gatsby-posts-core

This is the latest implementation from the v3.x release. This is the equivalent of mdx on the markdown side. It is powered by the webpack loader @orgajs/loader, which enables orga to be easily integrated with a much wider range of tools (e.g. next.js, webpack, create-react-app etc…).

Here is a list of my favorite features:

• render react components in org-mode file, just like mdx
• per file custom layout
• passing arbitrary data to layout component via #+key: value
• replace default elements with your own react components

Basically Your org files are powerful pages. the gatsby example project is a minimal setup. For more advanced example, you can draw some inspirations from the website (source code for https://orga.js.org).

There are a couple of gatsby themes you can choose from if you want some out of the box goodies. Also they are good resources for creating your own theme.

gatsby-theme-orga-posts-core

Powered by gatsby-transformer-orga, it transforms your org files into blog posts, with zero UI elements (it literally print out stringified JSON objects by default). It’s totally up to you to customize the look and feel.

gatsby-theme-orga-posts

A wrapper around gatsby-theme-posts-core, with opinionated UI design. Yet still customizable to certain extend through component shadowing.

gatsby-theme-orga-docs

Powered by gatsby-plugin-orga, this is what the website is using. It’s designed for documentation kind of websites, with swappable components (through shadowing)