How does one.el work?

In an org file containing all the pages of our website we can build the website under ./public/ subdirectory by calling either one-build or one-render-pages commands.

The only difference between those two commands is that before producing the HTML pages calling one-render-pages, one-build command cleans the subdirectory ./public/ and copies the content of ./assets/ subdirectory into ./public/ subdirectory.

So let's focus on one-render-pages command.

For each page of our website, the function one-render-pages uses the render function set in ONE org property of the page to produce the HTML string representing the page and stores it in an index.html file whom path is determined by CUSTOM_ID org property of the page.

Render functions are at the heart of one.el mechanism. They determined how pages are rendered. Specifically, render functions are regular Elisp functions that takes 3 arguments

  • page-tree: corresponding to the parsed tree of the org entry defining the page,

  • pages: the list of pages,

  • global: a plist of global informations that are computed once in one-render-pages (see one-add-to-global) before rendering the pages

and return HTML strings.

For instance, the following hello-world function 

(defun hello-world (page-tree pages global)
      "<h1>Hello world!</h1>")

defines a valid render function. We can use it to build a website like this. In an empty directory, we create a file named one.org with the following content: 

* The home page
:PROPERTIES:
:ONE: hello-world
:CUSTOM_ID: /
:END:
* Blog post 1
:PROPERTIES:
:ONE: hello-world
:CUSTOM_ID: /blog/page-1/
:END:

We visit that file and call one-build command. It produces the following files 

.
├── one.org (already there)
└── public
    ├── blog
    │   └── page-1
    │       └── index.html
    └── index.html

and both files ./public/blog/page-1/index.html and ./public/index.html have the same content: 

<h1>Hello world!</h1>

Therefore if we serve the website in ./public/ directory at http://localhost:3000 we can access the two "Hello world!" pages at http://localhost:3000/blog/page-1/ and http://localhost:3000.

That's it! This is how one.el works under the hood.

one.el comes with predefined render functions, a custom CSS style sheet and a custom org export backend which are used all together to build that documentation for instance.

See Getting started to start a new project with those defaults.

See one-default render function to take inspiration and write your own render functions.

PREVRANDOMNEXT