Home A - Z
Menu

An Otter Wiki

Blame

378010 Ralph Thesen 2025-12-12 22:58:48
Added documentation for HTML_EXTRA_HEAD and HTML_EXTRA_BODY
1 
# Customization
2
d817d4 Ralph Thesen 2026-03-24 20:39:22
Wording
3
## How to customize your wiki
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
4
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
5
An Otter Wiki was not designed with the idea that user-defined styles and code might become necessary. However, since there is a need, a way to add CSS, JS and HTML has been added.
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
6
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
7
There are currently two ways to customize the wiki:
8
- Using `custom` directory to be able to add custom CSS, JS and HTML
9
- Using env variables for small HTML tweaks
10
11
Both methods work independently of each other.
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
12
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
13
### Using `custom` Directory
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
14
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
15
The template automatically loads several custom files which are empty by default. You can mount a directory into the container to provide the following customizations:
16
- `custom.css` - custom CSS styles (from version **2.3.1**)
17
- `custom.js` - custom JavaScript (from version **2.3.1**)
18
- `customHead.html` - custom HTML injected into the `<head>` section (from version **2.15.0**)
19
- `customBody.html` - custom HTML injected into the `<body>` section (from version **2.15.0**)
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
20
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
21
For example, with a `docker-compose.yaml` like this:
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
22
```yaml
23
version: '3'
24
services:
25
otterwiki:
26
image: redimp/otterwiki:2
27
restart: unless-stopped
28
ports:
29
- 8080:80
30
volumes:
31
- ./app-data:/app-data
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
32
# a custom local directory with a custom.css, custom.js, customHead.html and customBody.html
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
33
- ./custom:/app/otterwiki/static/custom
34
```
35
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
36
> [!NOTE]
37
> In case of a local deployment the browser might cache the web app, so users are recommended to clear cookies and site data if the changes to `custom.js` or `custom.css` are not visible immediately even after restarting the docker
38
39
### Using Environment Variables to Tweak HTML
40
41
The HTML body and head of every html rendered can be tweaked via `HTML_EXTRA_HEAD` and `HTML_EXTRA_BODY` environment variables.
42
43
This can be used for small tweaks that don't require big amounts of code.
44
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
45
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
46
## Examples
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
47
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
48
If you've made improvements that you'd like to share, don't forget, pull requests are always welcome. Or upon up an [issue](https://github.com/redimp/otterwiki/issues) post your code and a screenshot.
49
50
Check [otterwiki/docs/custom_css_example](https://github.com/redimp/otterwiki/tree/main/docs/custom_css_example) on github for ready-to-test examples.
51
52
### Serif Pages
53
54
This is an example `custom.css` that uses the serif font
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
55
`Baskervville` for the content rendered in the page.
56
57
```css
58
@import url('https://fonts.googleapis.com/css2?family=Baskervville');
59
60
.content > .page {
61
font-family: 'Baskervville', serif;
62
font-weight: 400;
63
}
64
```
65
2e88a6 Ralph Thesen 2024-03-23 23:06:53
reorganized customization
66
![](/Customization/a/baskervville-page.png)
f6e6a2 Ranbeer Malhotra 2025-07-28 13:34:33
Update customization.md: add a side note Update the title to "custom directory" since a single directory is mounted in the example below
67
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
68
### Adding the "Fork me on github" ribbon
378010 Ralph Thesen 2025-12-12 22:58:48
Added documentation for HTML_EXTRA_HEAD and HTML_EXTRA_BODY
69
9c5dd8 Ivan Novokhatski 2025-12-18 13:16:31
Documentation updates (#4) * updated 'Content and Editing Preferences' variables * updated and reworked customization.md * updated versions for custom html
70
This is an example of adding the "Fork me on github" ribbon using env variables for custom HTML.
378010 Ralph Thesen 2025-12-12 22:58:48
Added documentation for HTML_EXTRA_HEAD and HTML_EXTRA_BODY
71
72
```yaml
73
services:
74
otterwiki:
75
image: redimp/otterwiki:2
76
restart: unless-stopped
77
ports:
78
- 8080:80
79
environment:
80
HTML_EXTRA_HEAD: <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.3/gh-fork-ribbon.min.css" />
81
HTML_EXTRA_BODY: <a class="github-fork-ribbon right-bottom" href="https://url.to-your.repo" data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
82
volumes:
83
- ./app-data:/app-data
84
```
85
86
![](/Customization/github-ribbon.jpg)
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
87
1968a6 Freddy Heppell 2026-01-13 22:12:44
Document custom fancyblocks
88
### Custom Fancy Block Styles
89
90
If a non-standard style name is used for a Fancy Block, it will be rendered with the class `alert-[style name]`. This allows you to define your own styles in `custom.css`.
91
92
```md
93
::: extradanger
94
## Watch Out!
95
96
This Fancy Block has custom styles
97
:::
98
```
99
100
You will likely need to add styles for both light and dark modes, since the dark mode styles for the base alert will override your styles for light mode.
101
102
```css
103
.alert-extradanger {
104
background-color: yellow;
105
border: 5px dashed black;
106
border-radius: 0;
107
}
108
109
.dark-mode .alert-extradanger {
110
background-color: #666600;
111
border: 5px dashed yellow;
112
border-radius: 0;
113
}
114
```
115
51c6a9 Freddy Heppell 2026-03-23 10:44:38
Merge remote-tracking branch 'origin/main' into per-page-styles
116
![](/Customization/custom-fancyblock.png)
272b86 Freddy Heppell 2026-03-23 10:45:26
Fix heading hierarchy
117
118
### Styling individual pages or categories
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
119
120
A data attribute set to the path is set on the `<body>` of each page (`data-page-path`) and index (`data-index-path`) to allow styling or JavaScript functionality on individual pages.
121
122
The path is turned into a slug in each section, for example _My Category/My Page_ becomes `my-category/my-page`.
123
124
These are some examples of potential style customisations:
125
4cb883 Freddy Heppell 2026-03-23 10:45:26
Fix heading hierarchy
126
#### Target a Specific Page
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
127
ea5594 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
128
Hides the sidebar on the homepage only
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
129
130
```css
131
body[data-page-path="home"] .extra-nav {
132
display: none;
133
}
134
```
135
272b86 Freddy Heppell 2026-03-23 10:45:26
Fix heading hierarchy
136
#### Style all pages in a category
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
137
138
Applies a different colour to pages in _My Category_.
139
140
```css
141
body[data-page-path^="my-category/"] h1 {
142
color: darkred;
143
font-weight: bold;
144
}
145
```
146
272b86 Freddy Heppell 2026-03-23 10:45:26
Fix heading hierarchy
147
#### Style a Category Index
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
148
e14230 Freddy Heppell 2026-01-16 01:32:44
Small wording update
149
> [!NOTE]
150
> The whole wiki page index has a `data-index-path` of `/`
151
152
Turns the index listing into a one-column list for _My Category_.
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
153
154
```css
155
/* body[data-index-path^="my-category/"]
156
to apply to subcategories as well*/
157
body[data-index-path="my-category"] .pageindex-columns {
158
columns: 1
159
}
d817d4 Ralph Thesen 2026-03-24 20:39:22
Wording
160
```