66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# My website platform
|
|
|
|
I use this custom lua HTTP server for my personal web page. It works with lua-written pages, as well as markdown pages. It is completely customizable.
|
|
|
|
## How to use?
|
|
|
|
Compile with the provided `Makefile` (you will need `mklua`). Then, just use the `bin/website` binary. It accepts one argument - the config. The config is a lua file that must return an object with these fields:
|
|
|
|
- port: what port to bind to
|
|
- luapages: a `package.path`-like string for resolving lua pages
|
|
- pages: a `package.path`-like string for resolving markdown pages
|
|
- static: a `package.path`-like string for resolving static resources
|
|
- path: a `package.path`-like string for resolving custom plugins and lua libraries
|
|
- pages_base: a lua package name to be used as the base page template
|
|
|
|
Anything else is up to the user's implementation. However, the built-in plugins work with these additional fields:
|
|
|
|
- title: the default title of the website
|
|
- routes: any additional routes that should be added to the navbar, if any
|
|
- ignores: a lua pattern, that ignores a certain page from listing when its top-most segment matches
|
|
|
|
You can read any other config values from the config object.
|
|
|
|
## Plugins and templating
|
|
|
|
Templating is done via the tools, given in the `template` package. It has two fundamental APIs: `elements` and `slot`. Any field from `elements` is a function that accepts an object that contains a map of attributes and a list of children and returns a valid HTML. Then, `slot` is a function that may be used in place of `elements`. It calls a single callback with the current page being templated and a callback to emit more elements, results of `elements`. This is used when you want to generate HTML procedurally.
|
|
|
|
Example:
|
|
|
|
```lua
|
|
local e = require "template".elements;
|
|
local slot = require "template".slot;
|
|
|
|
...
|
|
|
|
return e.div {
|
|
class = "my-class",
|
|
|
|
e.span { "This is some text" },
|
|
e.span "This is a short form of the above",
|
|
|
|
slot(function (self, emit)
|
|
emit(e.span { "The current page is " .. self.path });
|
|
for i = 1, 10 do
|
|
emit(e.span { tostring(i) });
|
|
end
|
|
end),
|
|
}
|
|
```
|
|
|
|
The above will emit HTML like this:
|
|
|
|
```html
|
|
<div class="my-class">
|
|
<span>This is some text</span>
|
|
<span>This is a short form of the above</span>
|
|
<span>The current page is [page path]</span>
|
|
<span>1</span>
|
|
<span>2</span>
|
|
<span>3</span>
|
|
...
|
|
</div>
|
|
```
|
|
|
|
Three plugins are available by default - breadcrumbs, list and navbar. They can be used to build out a page.
|