Introduction
Summary
Fronde is a static website generator for Org, written in Ruby and Emacs Lisp (elisp). It enables you to concentrate on your writing, and manage all the needed steps to build and publish your website.
You can refer to the read me file for a quick list of the main features.
Nomenclature
This project name is fronde and will always be written normally
though this document to refer to this project as a whole. As such, it
will also be capitalized when used as the first word of a sentence. But
when it is written as fronde
, it will always refer to the
provided program you can call in your terminal.
This document uses the short name Emacs to refer to the GNU Emacs editor or capabilities.
Frequently Asked Questions
Why do you think we need another static website generator?
My main reason to write fronde, is that I was looking for a static website generator, which provides (good) support for Org as a source format. But they somehow all lack of it. The second main reason I wrote this, instead of dealing with a pure Org publish config, was my need to easily amend the generated HTML. I’m not an elisp expert and I would like to have some generic solution for all the tiny websites I’m maintaining. In short, the main feature of this project is surely its templates support.
Where does this name come from?
A fronde is the french word for a sling. This name was chosen as a tribute to the french newspaper « La Fronde », created by Marguerite Durand in France in 1897. This was the first all-women written and edited newspaper in the world. Marguerite Durand said about it in one of her editorial1 that her newspaper was « comme les autres journaux… pas plus amusant » (which may be translated as “just like other newspapers… as boring”).
As such, fronde is like all other static website generator… as boring. However, like its illustrious reference, fronde wishes to help empowering people, offering them a tool to express themselves on the Web.
Opinionated you say?
Fronde is built with some strong opinion about what a static website generator should be, and more specifically, what should it be for Org.
- Org is a powerful tool that enables you to publish your writings in a wide range of formats. Its markup is easy to learn and as readable and as convenient as Markdown's. That's why fronde will never support any other markup language.
- However Org HTML export should be more easily expandable. That’s why fronde gives you the templates feature and introduces new formatting tags for the preamble and postamble sections.
- Org writers should already be Emacs users, that’s why fronde will directly call Emacs to convert your Org files to HTML. There is no need to use Pandoc or org-ruby if you already have Emacs.
- You may want to author a wide variety of things, and managing all these projects inside your Emacs configuration may be a nightmare. You also may want to apply different settings for different projects. That’s why fronde is totally independent from your Emacs settings and enables you to organize your projects as you wish.
What will come next?
We are already aware of some limitations we would like to remove:
TODO Allow themes to provide configuration options
Themes should be able to declare a set of default
templates
or specific Org export options
TODO Better protected upgrade
For example, Rakefile should only be overwritten after upgrade of the gem.
TODO Create a themes portfolio
Source code
The canonical repository is located at https://git.umaneti.net/fronde. A mirror also exists on Github.
Getting started
Installation
Fronde is a Ruby gem and thus you need a working Ruby environment to use it. Fronde requires at least ruby 2.7 to work (though this version is no more maintained, you should really move to ruby 3.1 as soon as possible).
You may already have Ruby installed on your computer. You can check
inside a terminal emulator by typing: ruby -v
. You also
need the rubygems package manager, which may also be already installed
on your system. You can check it too with the following command:
gem -v
.
Install ruby with your system package manager
See the official ruby lang website to find out about options when installing a ruby environment on your system.
Some operating systems already package the right ruby version to use:
Archlinux-like
On Archlinux, Manjaro or Parabola, you just have to install the
packages rubygems
(which will install ruby
as
a dependency):
sudo pacman -S ruby rubygems
Debian-like
On Debian, Ubuntu, Mint… you just have to install the package
ruby
(which will install ruby-rubygems
as a
dependency):
sudo apt install ruby
Others
Ruby seems to be well packaged for Fedora, Red Hat or OpenMandriva, thus it should not be a problem for you to install it.
Install ruby with RVM
RVM allows you to install different ruby versions on the same machine. It could be interesting when you are already a ruby developer.
We recommend that you use a dedicated gemset for fronde, to avoid polluting your other projects.
rvm get latest
rvm install ruby-3.2.2
rvm use ruby-3.2.2@fronde --create
Install Fronde
As soon as you have a working ruby environment, you just need to install it as any other gem:
gem install fronde
Build Fronde from sources
You may also want to install a development version of fronde, directly from its source code repository. We won’t describe this procedure in detail as it should only be used by developers or advanced users. But still, here are the commands you can used to build fronde from the sources.
git clone https://git.umaneti.net/fronde
cd fronde
gem install bundler
bundle install
gem build fronde.gemspec
Then, you can install fronde from this new locally built gem file (obviously, you must adapt the following command with the fronde version number you just built):
gem install fronde-0.4.0.gem
Creation of a website
A fronde project is essentially just a folder containing the
configuration of your website and a subfolder containing the org files
to publish. fronde requires a local installation of org-mode to work,
and will generate various configuration files you are not expected to
modify. To set up all these things, you must use the
fronde init
command.
Thus, to create a new fronde website, you must create an empty folder and move to this new folder in your terminal:
mkdir yourproject
cd yourproject
Now, you can run the fronde init
command with some
arguments:
fronde init -t "My brand new website"
The following arguments are allowed:
- -a (–author)
-
Set up the default author name (see the
author
config key) - -l (–lang)
-
Set up the default lang of your website (see the
lang
config key) - -t (–title)
- Set up the title of your first page
At the end of the init process, fronde will automatically open Emacs
on the first page of your website. You can directly write in it or close
it and come back to it later. This file is stored in the default
src
source subfolder as
src/index.org
.
Your project now consist of the following file hierarchy:
yourproject/
├── config.yml # main config file
├── .dir-locals.el # Emacs per-directory local variables file
├── lib/ # required dependencies
├── public_html/ # output folder
│ └── assets/
├── Rakefile # fronde-generated ruby related file
├── src/
│ └── index.org # your first website page
└── var/ # variable files used during operation
Fronde relies a lot on files stored in the lib
and
var
folders. You should never try to remove them by
yourself.
Creation or edition of a page
To create a new page for your website, or to edit an already existing one, you are totally free to use the tool you want. Pages are just regular Org files, without any specific modifications. If you already have a bunch of them, you can use them without any changes.
By default, without any other configuration options, the website
pages must be stored in a folder named src
at the root of
your project. However you can configure any other sources folder you want, even one that is
not in your project directory.
In parallel to your regular Org workflow, fronde provides command to
help you create or edit pages for your website: the
fronde open
command.
The most simple use case is to call fronde open
with a
file path and it will open that file in your default EDITOR
(which should be Emacs).
fronde open src/index.org
When creating a new page, this command accepts the following arguments:
- -a (–author)
- Set the author name of the page
- -l (–lang)
- Set the language of the page
- -t (–title)
- Set the title of the page
If you use the --title
argument, instead of giving a
full file path argument, you can just give the folder path where you
want to save the new file, and the command will create the document with
a web-ready name.
fronde open -a Alice -t "My new page’s shiny, isn’t it?" src
ls src
> index.org my-new-page-s-shiny-isn-t-it.org
And now src/my-new-page-s-shiny-isn-t-it.org
contains:
#+title: My new page’s shiny, isn’t it?
#+date: <2020-11-12 Thu. 11:25:58>
#+author: Alice
#+language: en
Building the website
Once you have written some content, you can convert your org files to
HTML with the fronde build
command.
fronde build
Because this building process makes a direct use of the org-mode
publishing feature, it will rebuild only files changed since the last
command invocation. If you want to force a full rebuild, you can pass
the --force
arguments to the command.
fronde build -f
To review what you just built, you can use the
fronde preview
command, which will start a local webserver
and open your default web browser on the home page of your project.
fronde preview
Publishing the website
Advanced usage
Config File
All the fronde configuration is stored in one YAML file named
config.yml
and stored at the root of your project. If the
file does not exist a default one will be created the first time you run
any fronde
command.
The following explains all possible configuration options for fronde,
which may be put in file named config.yml
at the root of
your static website project. The options are listed in alphabetical
order. However, they can be put in any order in the
config.yml
file.
author
The author
option stores the default author name of your
org files. This value is used when you create a new file. It is
not used by the regular Org mode publishing process. You must
be sure that your org files contains an #+author:
metadata
field before publishing them.
This value is used in the generation of the blog index page and the main atom feed.
---
author: Alice Doe
The default author
setting is your user name on your
current computer session.
domain
The domain name pointing to where your static website is expected to be hosted. This value is used to generate absolute path to your files on your expected host name (for example in the Atom feeds).
Its value is expected to not end with a slash. That
is to say https://example.com
is valid,
whereas https://example.com/
is not.
By default, your static website is expected to be hosted at the root
of your domain name (like https://example.com/index.html
).
If it is not the case and your fronde static website is hosted in a
subfolder of your main website, you must add this subfolder to the
domain
value. Thus,
https://example.com/example
or
https://example.com/complex/example
are
valid values too.
---
domain: https://alice.doe.name
The default domain
value is an empty string.
gemini_public_folder
The gemini_public_folder
option stores the path to the
folder, which will contains the generated gemtext files, ready for
Gemini publication.
The default gemini_public_folder
value is
public_gmi
(at the root of your project).
gemini_remote
The gemini_remote
option contains an rsync like
destination string, which will be used to published your capsule when
using the sync:push
rake task. For example
user@domain:/var/www/mycapsule/
There is no default value for gemini_remote
. Publication
of your capsule will be skipped if there is no value for
gemini_remote
.
html_public_folder
The html_public_folder
option stores the path to the
folder, which will contains the HTML generated files, ready for Web
publication.
The default html_public_folder
value is
public_html
(at the root of your project).
html_remote
The html_remote
option contains an rsync like
destination string, which will be used to published your website when
using the sync:push
rake task. For example
user@domain:/var/www/mywebsite/
There is no default value for html_remote
. Publication
of your website will be skipped if there is no value for
html_remote
.
lang
The main locale your website will be written in. Its value must comply with the ISO 639-1 standard.
---
lang: en
The default lang
setting is that of your current
computer.
sources
The sources
option stores an array of all source
folders, where your org files to be published are. This enables you to
gather from various different places (even at some absolute path in your
computer) in your website.
Each source listed in that array is an object, which must use the following keys:
- path
- [string] path to the folder containing the file to exports
- name
- [string, optional] key used to generate the Org “project” name. This name never appears in a generated file, it is more like an internal id. Defaults to the last dirname of the path value.
- title
- TODO
- recursive
- [boolean, optional] whether the path should be exported recursively. Defaults to True
- exclude
- [string, optional] Regexp of files to not export for this source. Default to nothing (no files to exclude).
- target
-
[string, optional] Path where to put the exported files, relative to the
html_public_folder
orgemini_public_folder
folder. Defaults to the source name at the root of the public folder. - is_blog
- [boolean, optional] Whether this source should be considered as a blog and thus, serves to generate blog index, tags indexes and atom feeds.
- theme
- [string, optional] Theme name to use for this source. Defaults to “default”.
- type
- [string, optional] Type of the exporter to use. Fronde currently supports only “html” and “gemini”. Defaults to “html”.
If one of your sources is expected to use all default settings,
instead of an object, you can just provide the source path as a string.
Look at the src
source in the example bellow.
---
sources:
- src
- path: src/news
is_blog: true
If you don’t provide any sources
option, it fallbacks to
support only one source folder named src
at the root of
your project directory, as if the sources
option has
been:
---
sources:
- path: src
target: .
name: src
recursive: yes
Not setting the sources
option is different from giving
it the following exact value:
---
sources:
- src
In the first case, as nothing as been given for the
sources
option, its default value will use .
as its target directory, which means to put generated HTML files
directly at the root of the html_public_folder
(which
defaults to public_html
). But in the later case, the
generated target will be the src
folder inside the
html_public_folder
, which will be, by default,
public_html/src
.
Thus, if you have a very simple website with only one source, you
should avoid setting the sources
options, or be very
precise in what you specify.
templates
The templates
option enables you to customize the built
HTML files, whatever source they come from. The main idea behind this is
to add HTML fragments to the generated files.
The templates
option stores an array of
template, each one documenting an HTML fragment to insert or
move at some place in a specified generated file. Each template listed
in that array is an object, which must use the following keys:
- type
-
[string] how the template should be inserted or moved in the HTML
document. Can be either
before
,after
orreplace
. It defaults toafter
. - content
- [string] the HTML fragment to insert or replace. This value will be evaluated before insertion and some tags will be replaced in a context sensitive manner. See the Preamble/Postamble/Templates formatting tags section for the details.
- selector
-
[string] a CSS selector specifying where to insert the new fragment. For
example, if this value is
#main p:first-child
and the current templatetype
isafter
, then the currentcontent
will be placed after the first HTML tagp
inside a container, which has anid
ofmain
. - path
-
[string, optional] the current template will apply only to generated
HTML files matching this glob pattern. This pattern must match against a
published path. That means, for a HTML document stored at
public_html/some/folder/doc.html
, the path could be/some/folder/doc.html
or/some/folder/*.html
, but notpublic_html/…
. - source
- [string, optional] The aim of this option is to target, with a CSS selector, any part of the HTML document, in order to move it elsewhere. See example below.
The content
and the source
options are
incompatible: either you have a content
or a
source
, never both of them. This is because either you want
to add a new content to your document (using
content
) or you want to move an existing content
of your document (using source
). In both case, the
destination is taken from the selector
option.
For example, if you want to hide social media meta
tags
in the head of your generated HTML files, you can use the
following templates
setting, which will add a bunch of
meta
tags before the title
of any
generated HTML file:
---
templates:
- type: before
selector: title
content: |
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/">
<meta property="dc.publisher" content="%a">
<meta property="dc.type" content="text">
<meta property="dc.format" content="text/html">
<meta property="dc.title" lang="%l" content="%t">
<meta property="dc.description" lang="%l" content="%x">
<meta property="dc.language" content="%l">
<meta property="dc.date" content="%I">
<meta property="dc.rights" content="%L">
<meta name="twitter:card" content="summary">
<meta name="twitter:creator" content="@fsfe">
<meta property="og:type" content="article">
<meta property="og:title" content="%t">
<meta property="og:article:published_time" content="%I">
<meta property="og:url" content="%u">
<meta property="og:locale" content="%l">
<meta property="og:description" content="%x"> <meta property="og:site_name" content="My wonderfull website">
Another example: if you want, for example, to move the generated Org
table of content before the main #content
div (by default,
the Org publish process puts it inside this div). As we
specified a path
option, this replacement occurs only for
HTML documents under the /docs
folder.
- type: before
selector: div#content
source: nav#table-of-contents
path: "/docs/*.html"
Preamble, Postamble, and Templates formatting tags
This section documents the percent-tags you can use in the preamble or postamble of your sources, or in any of your templates. This tags will be replaced by their corresponding content when you will build your website. The values are context sensitive, taken from the currently evaluated Org file, or by default from the config of your project.
- %a
- the raw author name of the current Org file, or the one given in the config file.
- %A
-
the HTML rendering of the author name, equivalent to
<span class="author">%a</span>
. - %d
-
a short date HTML representation, equivalent to
<time datetime="%I">%i</time>
. - %D
- the full date and time HTML representation.
- %i
- the raw short date and time.
- %I
- the raw ISO 8601 date and time.
- %k
- the current Org file keywords separated by commas.
- %K
- the HTML list rendering of the keywords.
- %l
- the lang of the document, or the one given in the config file.
- %L
- the license information, taken from the config file.
- %n
- the fronde name and version.
- %N
- the fronde name and version with a link to the project home.
- %s
-
the subtitle of the current Org file (from
#+subtitle:
). - %t
-
the title of the current Org file (from
#+title:
). - %u
- the web path to the related published HTML document.
- %x
-
the raw description (
x
as in eXcerpt) of the current Org file (from#+description:
). - %X
-
the description, enclosed in an HTML
p
tag, equivalent to<p>%x</p>
Rake tasks
Like a lot of ruby project, fronde exposes some Rake tasks. You can discover
them with the rake -T
command.
Marguerite Durand. « En cinq ans ». La Fronde, no 1832. 15th December 1902. https://gallica.bnf.fr/ark:/12148/bpt6k67059454.item↩︎