add documentation about custom pages

1 files changed, 116 insertions, 0 deletions

diff --git a/doc/administration/custom-pages.rst b/doc/administration/custom-pages.rst
new file mode 100644
index 0000000..81354d5
--- /dev/null
+++ b/doc/administration/custom-pages.rst
@@ -0,0 +1,116 @@
+Custom Pages
+############
+
+Sometimes it is necessary to add custom static content to your website. For
+example, a legal requirement might be to have an `Impressum
+<https://en.wikipedia.org/wiki/Impressum>`__, a privacy policy, contact
+information or similar things on a website. Or you simply want to add some
+information about your instance of Fietsboek, links to other sites, ...
+
+Such pages can not be provided by Fietsboek out of the box, as they are very
+customized to the particular installation, and as such, Fietsboek provides a
+way to include custom pages. Those pages have the benefit of being embedded in
+Fietsboek's menu and layout, so they don't look out of place and can easily be
+found.
+
+.. note::
+
+    Please note that Fietsboek is not a general purpose content management
+    system for text. As such, the functionality is rather rudimentary and meant
+    for basic tasks such as the aforementioned legal documents.
+
+    Complex documents can always be done outside of Fietsboek, or by modifying
+    Fietsboek's source in your local installation.
+
+Writing A Page
+--------------
+
+Pages are written in Markdown and as such support some basic formatting
+functionality [1]_. In addition to the content, a page also has some metadata
+that tell Fietsboek when to show it, where to place it in the menu, ...
+
+An example page could look like this:
+
+.. code:: markdown
+
+    Title: Open Source
+    Link-name: Open Source
+    Slug: open-source
+    Locale: en
+    Show-to: everyone
+    Index: 1
+
+    # Fietsboek is Open Source!
+
+    You can contribute to **Fietsboek** [on Gitlab](https://gitlab.com/dunj3/fietsboek)!
+
+The metadata is provided in form of ``Key: value`` attributes at the start of
+the file. The rest of the file is interpreted as Markdown and rendered to HTML.
+
+The supported attributes are:
+
+Title : required
+    The title of the page, as it should be shown in the title bar of the browser.
+
+Link-name : required
+    The name of the link, as it is rendered in the menu.
+
+Slug : required
+    The slug of the page, as it appears in the URL. The page is reachable under
+    ``https://{your-host}/page/{page-slug}``.
+
+Locale : optional
+    Optional filter for the page locale. The filter is given as a regular
+    expression, the page is only shown if the expression matches the user's
+    locale. Multiple locale filters can be given, in which case any of them
+    have to match in order for the page to be shown.
+
+Show-to : optional
+    Determines whether the page should be shown to everyone (``everyone``),
+    only to logged in users (``logged-in``) or only to logged out users
+    (``logged-out``).
+
+Index : optional
+    Determines the position of the item in the menu. A higher index means the
+    item is more to the right. Pages with negative index are left of
+    Fietsboek's own menu, pages with positive index are right of Fietsboek's
+    own menu, and pages with index 0 (the default) are not rendered in the menu
+    (but still accessible via the link).
+
+The source code of a page (including the metadata and attributes) should be
+saved at a path that is accessible by Fietsboek.
+
+
+Including Pages
+---------------
+
+After you have written and saved the page, you can include it via the
+configuration file. The key ``fietsboek.pages`` is a list of paths to pages:
+
+.. code:: ini
+
+    [app:main]
+    # ...
+    fietsboek.pages =
+        /fietsboek/pages/page1.md
+        /fietsboek/pages/page2.md
+
+You can also include a directory, in which case all ``.md`` files of that
+directory will be included:
+
+.. code:: ini
+
+    [app:main]
+    # ...
+    fietsboek.pages =
+        /fietsboek/pages/
+
+Tips & Tricks
+-------------
+
+You can use the ``Locale`` filter to provide localized versions of your pages.
+If you keep the ``Slug`` the same between different languages, you can even
+re-use the same URL!
+
+.. [1] A basic syntax overview is for example here:
+   https://www.markdownguide.org/basic-syntax/