1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
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. However, Fietsboek provides a way to
include custom static 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/
Overwriting the Home Page
-------------------------
If you set a slug of ``/``, you can overwrite Fietsboek's custom home page:
.. code:: markdown
Title: Home
Slug: /
Link-name: home
Welcome to Fietsboek!
=====================
Note that you can use the same ``Locale`` and ``Show-to`` filters for the home
page as you can for other custom pages. If no matching home page is found,
Fietsboek will fall back to the default.
When defining your own home page, make sure to still include it in the
configuration!
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/
|
