aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorGravatar Étienne Deparis 2020-10-28 21:51:41 +0100
committerGravatar Étienne Deparis 2020-11-12 16:06:03 +0100
commit6562da1cff27ea6c73a09315ffdd9c25d7b1b7ec (patch)
tree9c2a8c25b56ac62b774654bd9aa2451c92ad1a74
parentc372d6752f0797464ea20ef092564cc9a4df3068 (diff)
downloadfronde-6562da1cff27ea6c73a09315ffdd9c25d7b1b7ec.tar.gz
fronde-6562da1cff27ea6c73a09315ffdd9c25d7b1b7ec.tar.xz
fronde-6562da1cff27ea6c73a09315ffdd9c25d7b1b7ec.zip
docs: Begin to work on a real documentation
-rw-r--r--.yardopts1
-rw-r--r--CONFIG.org91
-rw-r--r--DOCUMENTATION.org660
-rw-r--r--README.org20
-rw-r--r--Rakefile16
-rw-r--r--fronde.gemspec (renamed from neruda.gemspec)6
6 files changed, 674 insertions, 120 deletions
diff --git a/.yardopts b/.yardopts
new file mode 100644
index 0000000..0ad64e6
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1 @@
+--private -m org --files DOCUMENTATION.org --asset tigre.png
diff --git a/CONFIG.org b/CONFIG.org
deleted file mode 100644
index 7522294..0000000
--- a/CONFIG.org
+++ /dev/null
@@ -1,91 +0,0 @@
-#+title: Fronde config.yml file
-#+author: Étienne Deparis
-#+lang: en
-#+description: Glossary of all possible configuration options for Fronde
-#+options: ^:{}
-
-This file explain 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.
-
-* ~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 by a slash. That is to say ~https://example.com~
-is a *valid* value, while ~https://example.com/~ is not. Its default
-value is an empty string.
-
-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 sub directory of
-your main website, you must add this sub folder to the ~domain~
-value. Thus, ~https://example.com/example~ or
-~https://example.com/complex/example~ are *valid* values too, while
-~https://example.com/example/~ or ~https://example.com/complex/example/~
-are not.
-
-* ~lang~
-
-The main locale your website will be written in. Its value must comply
-with the [[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes][ISO 639-1]] standard.
-
-* ~public_folder~
-
-The ~public_folder~ option stores the path to the folder, which will
-contains the generated files, ready for publication. It's default value
-is ~public_html~ (at the root of your project).
-
-* ~remote~
-
-The ~remote~ option contains an /rsync/ like destination string, which
-will be used to published your website when using the ~sync:push~ /rake/
-task. For exemple ~user@domain:/var/www/mywebsite/~
-
-* ~title~
-
-The ~title~ option stores the default title 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 ~#+title:~ metadata field before publishing them.
-
-This value is used in the generation of the blog index page and the main
-atom feed.
-
-* ~sources~
-
-The ~sources~ option stores an array of all source folders, where your
-org files to be published are. This allow you to gather 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.
- Defaults to the last dirname of the path value.
-- recursive :: [boolean, optional] wether the path should be exported
- recursively. Defaults to True
-- exclude :: [string, optional] Regexp of files to not export for this
- projects. Default to nothing (no files to exclude).
-- target :: [string, optional] Path where to put the exported files,
- relative to the ~public_folder~ folder. Default to the project name at
- the root of the ~public_folder~ folder.
-- is_blog :: [boolean, optional] Whether this project should be
- considered as a blog and thus, serves as source to generate blog
- index, tags indexes and atom feeds.
-- theme :: [string, optional] Theme name to use for this
- project. Defaults to “default”.
diff --git a/DOCUMENTATION.org b/DOCUMENTATION.org
new file mode 100644
index 0000000..ca2dd90
--- /dev/null
+++ b/DOCUMENTATION.org
@@ -0,0 +1,660 @@
+#+title: Fronde Documentation
+#+author: Étienne Deparis
+#+lang: en
+#+description: Glossary of all possible configuration options for Fronde
+#+options: ^:{} toc:3 num:3 H:4
+
+* Introduction
+
+** Summary
+
+*Fronde* is a static website generator for [[https://orgmode.org][Org]], written in Ruby and
+Emacs Lisp (elisp). It lets you contentrate about your writings, and
+manage all the needed steps to build and publish your Website.
+
+You can refer to the [[./README.org][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 always refer to the [[https://www.gnu.org/software/emacs/][GNU Emacs]]
+editor or capabilities.
+
+** Frequently Asked Questions
+*** Why do you think we need another static website generator?
+
+The most known of them lacks of (good) support for Org as source
+format. 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 website I’m maintaining. To be short, the main
+feature of this project is surely its [[#templates_setting][templates support]].
+
+*** Where does this name come from?
+
+A /fronde/ is the french word for a [[https://en.wikipedia.org/wiki/Sling_(weapon)][sling]]. This name was chosen as a
+tribute to the french newspaper « La Fronde », created by [[https://en.wikipedia.org/wiki/Marguerite_Durand][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 editorial[fn:durand1902] that her newspaper was « comme les autres
+journaux… pas plus amusant » (what may be translated by “just like other
+newspapers… as boring”).
+
+[fn:durand1902] Marguerite Durand. « En cinq ans ». La Fronde,
+n^{o} 1832. 15th December 1902.
+https://gallica.bnf.fr/ark:/12148/bpt6k67059454.item
+
+
+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 should be a static
+website generator, and more specifically, what should it be for Org.
+
+- Org is a powerfull tool, which allows you to publish your writings in
+ a wide range of format. Its markup is easy to learn and as readable
+ and as convenient as Markdown. 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_setting][templates feature]] and introduces [[#formatting_tags][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 manage 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 let’s
+ you organize your projects as you wish.
+
+*** What will come next?
+
+We are already aware of some limitations we would like to leverage.
+
+**** TODO Allow theme to provide configuration options
+Themes should be able to declare a set of default ~templates~ or
+specific Org export options
+
+**** TODO Improve this documentation
+**** TODO Create a theme portfolio
+**** TODO Better protect upgrade
+
+For example, Rakefile should only be overwritten after upgrade of the
+gem.
+
+** Source code
+
+You can access the source code at: https://git.umaneti.net/fronde
+
+* Getting started
+
+** Installation
+
+Fronde is a [[https://rubygems.org/][Ruby gem]] and thus you need a working Ruby environment to use
+it. Fronde requires at least ruby 2.6 to work.
+
+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 [[https://www.ruby-lang.org/en/downloads/][official ruby lang website]] to know more about options to install
+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
+~ruby~ and ~rubygems~:
+
+#+caption: Ruby installation procedure on Archlinux-like system
+#+begin_src shell
+ sudo pacman -S ruby rubygems
+#+end_src
+
+**** Debian-like
+
+Ruby 2.6 does not seem to be available at all. However, on Ubuntu at
+least, ruby 2.7 is available. Thus you should try the following command:
+
+#+caption: Ruby installation procedure on Debian-like system
+#+begin_src shell
+ sudo apt install ruby2.7
+#+end_src
+
+**** Others
+
+Ruby 2.7 seems to be already well packaged for Fedora, Red Hat or
+OpenMandriva, thus it should not be a problem for you to install it.
+
+*** Install ruby with RVM
+
+[[https://rvm.io][RVM]] allows you to install different ruby versions on the same
+machine. It could be interesting when you are already a ruby
+developper.
+
+We recommand you to use a dedicated gemset for fronde, to avoid
+polluting your other projects.
+
+#+caption: Ruby installation procedure with RVM
+#+begin_src shell
+ rvm get latest
+ rvm use ruby-2.7.2@fronde --create
+#+end_src
+
+*** Install Fronde
+
+As soon as you have a working ruby environment, you just need to install
+it as any other gem:
+
+#+caption: Fronde gem installation procedure
+#+begin_src shell
+ gem install fronde
+#+end_src
+
+*** 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
+details as it should only be used by developpers or advanced users. But
+still, here are the commands you can used to build fronde from the
+sources.
+
+#+caption: Build sources procedure
+#+begin_src shell
+ git clone https://git.umaneti.net/fronde
+ cd fronde
+ gem install bundler
+ bundle install
+ gem build fronde.gemspec
+#+end_src
+
+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):
+
+#+caption: Fronde installation procedure from local gem file
+#+begin_src shell
+ gem install fronde-0.3.0.gem
+#+end_src
+
+** 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 setup 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:
+
+#+caption: Create a fronde project directory
+#+begin_src shell
+ mkdir yourproject
+ cd yourproject
+#+end_src
+
+Now, you can run the ~fronde init~ command with some arguments:
+
+#+caption: Initialize a fronde project
+#+begin_src shell
+ fronde init -t "My brand new website"
+#+end_src
+
+#+begin_tip
+The following arguments are allowed:
+
+- -a (--author) :: Set up the default author name (see the [[#author_setting][~author~ config key]])
+- -l (--lang) :: Set up the default lang of your website (see the [[#lang_setting][~lang~ config key]])
+- -t (--title) :: Set up the title of your website (see the [[#title_setting][~title~ config key]])
+#+end_tip
+
+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~
+[[#sources_setting][source]] subfolder as ~src/index.org~.
+
+Your project now consist of the following file hierarchy:
+
+#+begin_example
+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
+#+end_example
+
+#+begin_caution
+Fronde relies a lot on files stored in the ~lib~ and ~var~ folders. You
+should never try to remove them by yourself.
+#+end_caution
+
+** 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_setting][sources folder]] you want,
+even one, which is not in your project directory.
+
+In parallel of your regular Org workflow, fronde provides a little
+command to help you create or edit pages for your website: the ~fronde
+open~ command.
+
+The most simple use case is just to call it with a file path and it will
+open that file in your default ~EDITOR~ (which should be Emacs).
+
+#+caption: Open a page with the fronde open command
+#+begin_src shell
+ fronde open src/index.org
+#+end_src
+
+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.
+
+#+caption: Creation of a new page with the title argument
+#+begin_src shell
+ 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
+#+end_src
+
+And now ~src/my-new-page-s-shiny-isn-t-it.org~ contains:
+
+#+begin_example
+#+title: My new page’s shiny, isn’t it?
+#+date: <2020-11-12 Thu. 11:25:58>
+#+author: Alice
+#+language: en
+
+
+#+end_example
+
+** Building the website
+
+Once you have written some content, you can convert your org files to
+html with the ~fronde build~ command.
+
+#+caption: Build a fronde project
+#+begin_src shell
+ fronde build
+#+end_src
+
+#+begin_tip
+As this building process makes a direct use of the org-mode publishing
+feature, it will only rebuild changed files since the last command
+invocation. If you want to force a full rebuild, you can pass the
+~--force~ arguments to the command.
+
+#+begin_src shell
+ fronde build -f
+#+end_src
+#+end_tip
+
+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.
+
+#+caption: Build a fronde project
+#+begin_src shell
+ fronde preview
+#+end_src
+
+** Publishing the website
+
+* Advanced usage
+
+** Config File
+
+All the fronde configuration is stored in one [[https://en.wikipedia.org/wiki/YAML][YAML]] file named
+~config.yml~ and stored at the root of your project. If none exists, a
+default one will be created the first time you run any ~fronde~ command.
+
+The following document 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~
+:PROPERTIES:
+:CUSTOM_ID: author_setting
+:END:
+
+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.
+
+#+caption: Example of an author setting
+#+begin_src yaml
+ ---
+ author: Alice Doe
+#+end_src
+
+#+begin_note
+The default ~author~ setting is inferred from your user name on your
+current computer system session.
+#+end_note
+
+*** ~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).
+
+#+begin_caution
+Its value is expected to *not* end by a slash. That is to say
+~https://example.com~ is a *valid* value, while ~https://example.com/~
+is not.
+#+end_caution
+
+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 sub directory of
+your main website, you must add this sub folder to the ~domain~
+value. Thus, ~https://example.com/example~ or
+~https://example.com/complex/example~ are *valid* values too.
+
+#+caption: Example of a domain setting
+#+begin_src yaml
+ ---
+ domain: https://alice.doe.name
+#+end_src
+
+#+begin_note
+The default ~domain~ value is an empty string.
+#+end_note
+
+*** ~lang~
+:PROPERTIES:
+:CUSTOM_ID: lang_setting
+:END:
+
+The main locale your website will be written in. Its value must comply
+with the [[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes][ISO 639-1]] standard.
+
+#+caption: Example of a lang setting
+#+begin_src yaml
+ ---
+ lang: en
+#+end_src
+
+#+begin_note
+The default ~lang~ setting is inferred from your current system one.
+#+end_note
+
+*** ~public_folder~
+
+The ~public_folder~ option stores the path to the folder, which will
+contains the generated files, ready for publication.
+
+#+begin_note
+The default ~public_folder~ value is ~public_html~ (at the root of your
+project).
+#+end_note
+
+*** ~remote~
+
+The ~remote~ option contains an /rsync/ like destination string, which
+will be used to published your website when using the ~sync:push~ /rake/
+task. For exemple ~user@domain:/var/www/mywebsite/~
+
+#+begin_note
+There is no default value for ~remote~. Publication of your website will
+just be skipped.
+#+end_note
+
+*** ~title~
+:PROPERTIES:
+:CUSTOM_ID: title_setting
+:END:
+
+The ~title~ option stores the default title of your org files. This
+value is used when you create a new file with the ~fronde~ command.
+
+#+begin_warning
+*This setting is not used by the regular org mode publishing process*.
+You must ensure that your org files contains an ~#+title:~ metadata
+field before publishing them.
+#+end_warning
+
+This value is also used in the generation of the blog index page and the
+main atom feed as website title.
+
+*** ~sources~
+:PROPERTIES:
+:CUSTOM_ID: sources_setting
+:END:
+
+The ~sources~ option stores an array of all source folders, where your
+org files to be published are. This allow you to gather 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 [[https://orgmode.org/org.html#Project-alist][Org “project”
+ name]]. This name never appear in a generated file, it is more like an
+ internal id. Defaults to the last dirname of the path value.
+- recursive :: [boolean, optional] wether 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 ~public_folder~ folder. Default to the source name at
+ the root of the ~public_folder~ 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”.
+
+#+begin_tip
+If one of your source 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.
+#+end_tip
+
+#+caption: Example of a sources array setting
+#+begin_src yaml
+ ---
+ sources:
+ - src
+ - path: src/news
+ is_blog: true
+#+end_src
+
+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:
+
+#+caption: Default value of the sources option
+#+begin_src yaml
+ ---
+ sources:
+ - path: src
+ target: .
+ name: src
+ recursive: yes
+#+end_src
+
+#+begin_warning
+Not setting the ~sources~ option is different from giving it the
+following exact value:
+
+#+begin_src yaml
+ ---
+ sources:
+ - src
+#+end_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 ~public_folder~
+(which defaults to ~public_html~). But in the later case, the generated
+target will be the ~src~ folder /inside/ the ~public_folder~, what will
+be, by default, ~public_html/src~.
+
+Thus, if you have a very simple website with only one source, you should
+avoid to set the ~sources~ options, or be very precise in what you want.
+#+end_warning
+
+*** ~templates~
+:PROPERTIES:
+:CUSTOM_ID: templates_setting
+:END:
+
+The ~templates~ option let’s you customized the built html files,
+whatever source they come from. The main idea behind it, is to add
+HTML fragments to the generated files.
+
+The ~templates~ option stores an array of /template/, each of 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~ or ~replace~. It
+ defaults to ~after~.
+- 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 maneer. See the [[#formatting_tags][Preamble/Postamble/Templates
+ formatting tags]] section for the details.
+- selector :: [string] a CSS selector specififying where the new
+ fragment should be inserted. For exemple, if this value is ~#main
+ p:first-child~ and the current template ~type~ is ~after~, then the
+ current ~content~ will be placed /after/ the first HTML tag ~p~ inside
+ a container, which ~id~ is ~main~.
+- path :: [string, optional] the current template will only apply on
+ 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 not
+ ~public_html/…~.
+- source :: [string, optional] this option is incompatible with the
+ ~content~: either you have a ~content~ or a ~source~, never both of
+ them. 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.
+
+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:
+
+#+caption: Templates setting to add social media meta tags
+#+begin_src yaml
+ ---
+ 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">
+#+end_src
+
+Here is another example, if you want, for example, move the generated
+Org table of content before the main ~#content~ div (by default, the Org
+publish process put it /inside/ this div). As we specified a ~path~
+option, this replacment will only occur for HTML document under the
+~/docs~ folder.
+
+#+caption: Templates setting to move the table of content outside the #content div
+#+begin_src yaml
+- type: before
+ selector: div#content
+ source: nav#table-of-contents
+ path: "/docs/*.html"
+#+end_src
+
+** Preamble/Postamble/Templates formatting tags
+:PROPERTIES:
+:CUSTOM_ID: formatting_tags
+:END:
+
+This section documents the percent-tags you can use in the preamble or
+postamble of your [[#sources_setting][sources]], or in any of your [[#templates_setting][templates]]. This tags will
+be replaced by their corresponding content when you will build your
+website. Their value is context sensitive: it will take a value from the
+currently evaluated Org file, or by default 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 rfc3339 date and time.
+- %k :: the current Org file keywords separated by a comma.
+- %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 [[https://ruby.github.io/rake/][Rake]] tasks. You can
+discover them with the ~rake -T~ command.
diff --git a/README.org b/README.org
index ac4b18f..1ca0b57 100644
--- a/README.org
+++ b/README.org
@@ -10,8 +10,9 @@
#+attr_html: :style width:150px;float:right;margin-top:-4.5em;margin-left:2em;
[[file:./tigre.png]]
-Fronde is a static website generator made for [[https://orgmode.org][Org files]]. It improves the
-default Org HTML exporting/publishing routine.
+Fronde is an opinionated static website generator for [[https://orgmode.org][Org]]. It helps you
+converting Org mode files into websites, giving you full control over
+the publication process.
* Features
@@ -26,7 +27,7 @@ default Org HTML exporting/publishing routine.
- Can use different theme for different sources
- Supports tags and [[https://en.wikipedia.org/wiki/Atom_(Web_standard)][ATOM feeds]]
-* How to install it
+* Quick install
Fronde is a [[https://rubygems.org/][Ruby gem]]. You need a working Ruby environment to use it. We
recommand you to use [[https://rvm.io][RVM]] and a specific gemset. However it will works
@@ -35,21 +36,20 @@ with a global ruby installation too.
#+caption: Installation procedure with RVM
#+begin_src shell
rvm get latest
-rvm use ruby-2.6.3@fronde --create
+rvm use ruby-2.7.2@fronde --create
gem install fronde
#+end_src
Now, you're ready to create your first Fronde website.
#+begin_src shell
+mkdir mywebite
+cd mywebsite
fronde init -t "My first fronde website"
+fronde build
+fronde preview
#+end_src
* Going further
-All the Fronde configuration is stored in one [[https://en.wikipedia.org/wiki/YAML][YAML]] file named
-~config.yml~ and stored at the root of your project. If none exists, a
-default one will be created the first time you run any ~fronde~ command.
-
-You should read the [[./CONFIG.org][config file documentation]] to discover its various
-options.
+Please refer to the [[./DOCUMENTATION.org][documentation]].
diff --git a/Rakefile b/Rakefile
deleted file mode 100644
index 36a636b..0000000
--- a/Rakefile
+++ /dev/null
@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-begin
- require 'yard'
- require 'rspec/core/rake_task'
-
- RSpec::Core::RakeTask.new(:spec)
-
- YARD::Rake::YardocTask.new do |t|
- t.options = ['-m', 'org', '--no-progress',
- '--files', 'DOCUMENTATION.org',
- '--asset', 'tigre.png']
- end
-rescue LoadError
- warn 'You are not using the development bundle.'
-end
diff --git a/neruda.gemspec b/fronde.gemspec
index acb3246..adbcec8 100644
--- a/neruda.gemspec
+++ b/fronde.gemspec
@@ -5,10 +5,10 @@ require './lib/fronde/version'
Gem::Specification.new do |s|
s.name = 'fronde'
s.version = Fronde::VERSION
- s.summary = 'A simplistic way to create an Org static website.'
+ s.summary = 'An opinionated static website generator for Org'
s.description = <<~DESC
- An opinionated Org static website generator.
- Write your org-mode files, we take care of the rest.
+ Fronde helps you to convert Org mode files into websites, giving you
+ full control over the publication process.
DESC
s.authors = ['Étienne Deparis']
s.email = 'etienne@depar.is'