oblivious is a static site generator written in emacs-lisp, bash and
org-mode. It is designed to be minimalistic and extensible at the same time
and consists of a CLI written in under 100 lines of bash. The configuration of
the site is done using org-mode.
The general idea is to grab a copy of oblivious and then to create a
readme.org file at the root of your directory in order to configure your site:
# tree -a . ├── bin │ └── oblivious └── readme.org
Now initialize the new site and depending on what you’ve configured in your
readme.org something like this will be created. Note that the init command
also injects the configuration of your emacs export setup into your existing
emacs configuration (that is if you use vanilla or doom emacs):
# bin/oblivious init
# tree -a
.
├── assets <-------------------- you store stuff you created yourself here, e.g. pictures, logos, ...
├── bin <----------------------- the bin folder is where scripts used by oblivious can be tangled to
│ ├── .get_resources
│ ├── .git_user_info
│ └── oblivious
├── .config <------------------- this folder contains elisp files, such as the sites org-publish configuration
│ └── org-publish.el
├── .dir-locals.el <------------ use this to set up custom properties of your site, e.g. local org-ref setup or author and email for org-mode
├── .gitignore <---------------- apart from content everything autogenerated should be added to the .gitignore file
├── index
│ └── index.org <------------- this could be the landingpage of the site
├── partials <------------------ autogenerated html files
│ ├── footer.html
│ └── header.html
├── posts <--------------------- posts stores blog posts, e.g.: posts/how-to-use-oblivious/{index.org,img/example.png}
├── public <-------------------- this is where the finished site is exported to
├── readme.org <---------------- configuration of the site, contains src_blocks, which are loaded and/or tangled
├── static <-------------------- this is where stuff such as javascript will be downloaded into (unlike assets you don't keep track of this)
└── templates <----------------- contains org files which are tangled from the readme.org. Enable them with '#+include:...' or '#+setupfile:...'
Currently oblivious supports the following commands:
# bin/oblivious Description: oblivious is a bit of glue built around org-publish. It enables you to quickly set up a nice little website or blog with bash, emacs and orgmode. Obliviously you have no idea how to use this, you wouldn't be here otherwise. Here are some pointers: Usage: oblivious [command] Commands: init Init and inject org-publish config into your ~/.doom.d/config.el or ~/.emacs.d/init.el sync Load settings from your readme.org fetch Fetches resources you have defined (css and fonts) build Runs org-publish and creates your website observe TODO I really need to add this one: watch for file changes in the parent directory and its children, autorebuild release TODO Rebuild and add a signed commit with automated commit message, etc. * Display this Help
At this point it is noteworthy that in order to make everything extensible, I
set up oblivious to check if custom scripts are existing and if so just
execute those instead of the built-in funcitonality: for example if the file
bin/.init exists, the oblivious init command would execute it, instead of
the built-in init commands. This way you are able to customize pretty much
everything oblivious does.
Also there are a few things I’d like to mention as well:
- external resources are meant to be fetched, the general idea is to write a bunch of src blocks, which will be tangled into a download script. You don’t have to do this, but I found it to bequite handy and it makes self hosting and minimizing external resources quite simple.
- this started out as a quick weekend project and while I think I’ve actually built something quite nice, it currently is in more of a ‘works for me’ state than a polished product. I’m now two weekends in and have included most of the functionality I would like to have on my site, but I’m pretty sure a bunch of the underlying things should definitely be reworked.
- while I’m using org-publish here it is entirely possible to set up a different exporting backend such as ox-hugo.
- I’ve build
obliviouswith pipelines in mind, so one of my goals for this project is to be able to unattendedly batch export a site with the same results you get when exporting it from an emacs session - a few things I did, are not necessarily the best defaults to what you want to use: e.g. the batch processing steps are actually loading my emacs config, instead of just executing a bit of elisp.
- I have no idea how to use CSS, HTML and I’m no expert in bash, org-mode or emacs-lisp, so expect a fair amount of cargo culting, when you read this document.
- A bunch of the examples might be a bit unintuitive. For example: the knowledge graph is being tangled to an org-file, which contains an bash src block. This bash src block is then executed and it’s output is put into the tangled org document. This Output of the bash block is an export block which contains raw html, that is then directly embedded into the knowledge graph portion of the html export. The generated org file is then imported into the tags list using ‘#+include’. So basically things can get a bit complicated if you want them to be and sometimes, stuff like proper escaping can be quite important. You don’t need to do something like this, it works for me.
- Since the examples are quite unintuitive for I’ll probably split them up properly at a later point in time and make sure to document them properly.
At a later point in time I would very much like to see oblivious turn into a
tool, which provides a collection of patterns users can then reference in order
to set everything up. Specifically I’m thinking about something like this, where
the readme.org files contain handy bits and pieces of fancy configuration
users can simply include and start using in order to set up a site:
├── bin │ └── oblivious ├── patterns │ ├── bootstrap │ │ └── readme.org │ ├── exampleusers_custom_bootstrap_fork │ │ └── readme.org │ ├── visjs │ │ └── readme.org ... ... └── readme.org
The rest of this document contains everything necessary to create this little
blog. For now it serves as example of what can be done to set up a minimalistic
little site using oblivious (some information is not part of the html export,
e.g. setting configured in property drawers).
Have fun and enjoy!