# 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.