diff options
| -rw-r--r-- | doc/administration.rst | 1 | ||||
| -rw-r--r-- | doc/administration/configuration.rst | 1 | ||||
| -rw-r--r-- | doc/administration/custom-pages.rst | 116 |
3 files changed, 118 insertions, 0 deletions
diff --git a/doc/administration.rst b/doc/administration.rst index 3c5cf7f..7aa2393 100644 --- a/doc/administration.rst +++ b/doc/administration.rst @@ -9,6 +9,7 @@ Administration Guide administration/configuration administration/upgrading administration/backup + administration/custom-pages This guide contains information pertaining to the administration of a Fietsboek instance. This includes the installation, updating, configuration, and backing diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst index 272ac71..5268903 100644 --- a/doc/administration/configuration.rst +++ b/doc/administration/configuration.rst @@ -61,6 +61,7 @@ Most of the configuration is in the ``[app:main]`` category and looks like this: * ``fietsboek.data_dir`` sets the directory for data uploads. This directory must be writable by the Fietsboek process, as Fietsboek will save track images in there. +* ``fietsboek.pages`` see :doc:`custom-pages`. * ``email.from`` sets the sender of emails, for example for account verifications. * ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted: 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/ |