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
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
3
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
4
## Customizing Your Copy of the Wiki
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
5
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
6
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
7
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
8
There are currently two ways to customize the wiki:
9
- Using `custom` directory to be able to add custom CSS, JS and HTML
10
- Using env variables for small HTML tweaks
11
12
Both methods work independently of each other.
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
13
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
14
### Using `custom` Directory
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
15
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
16
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:
17
- `custom.css` - custom CSS styles (from version **2.3.1**)
18
- `custom.js` - custom JavaScript (from version **2.3.1**)
19
- `customHead.html` - custom HTML injected into the `<head>` section (from version **2.15.0**)
20
- `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
21
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
22
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
23
```yaml
24
version: '3'
25
services:
26
otterwiki:
27
image: redimp/otterwiki:2
28
restart: unless-stopped
29
ports:
30
- 8080:80
31
volumes:
32
- ./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
33
# 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
34
- ./custom:/app/otterwiki/static/custom
35
```
36
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
37
> [!NOTE]
38
> 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
39
40
### Using Environment Variables to Tweak HTML
41
42
The HTML body and head of every html rendered can be tweaked via `HTML_EXTRA_HEAD` and `HTML_EXTRA_BODY` environment variables.
43
44
This can be used for small tweaks that don't require big amounts of code.
45
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
46
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
47
## Examples
b59643 Ralph Thesen 2024-03-23 14:47:34
added how-to on customize the otterwiki theme
48
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
49
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.
50
51
Check [otterwiki/docs/custom_css_example](https://github.com/redimp/otterwiki/tree/main/docs/custom_css_example) on github for ready-to-test examples.
52
53
### Serif Pages
54
55
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
56
`Baskervville` for the content rendered in the page.
57
58
```css
59
@import url('https://fonts.googleapis.com/css2?family=Baskervville');
60
61
.content > .page {
62
font-family: 'Baskervville', serif;
63
font-weight: 400;
64
}
65
```
66
2e88a6 Ralph Thesen 2024-03-23 23:06:53
reorganized customization
67
![](/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
68
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
69
### 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
70
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
71
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
72
73
```yaml
74
services:
75
otterwiki:
76
image: redimp/otterwiki:2
77
restart: unless-stopped
78
ports:
79
- 8080:80
80
environment:
81
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" />
82
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>
83
volumes:
84
- ./app-data:/app-data
85
```
86
87
![](/Customization/github-ribbon.jpg)
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
88
1968a6 Freddy Heppell 2026-01-13 22:12:44
Document custom fancyblocks
89
### Custom Fancy Block Styles
90
91
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`.
92
93
```md
94
::: extradanger
95
## Watch Out!
96
97
This Fancy Block has custom styles
98
:::
99
```
100
101
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.
102
103
```css
104
.alert-extradanger {
105
background-color: yellow;
106
border: 5px dashed black;
107
border-radius: 0;
108
}
109
110
.dark-mode .alert-extradanger {
111
background-color: #666600;
112
border: 5px dashed yellow;
113
border-radius: 0;
114
}
115
```
116
51c6a9 Freddy Heppell 2026-03-23 10:44:38
Merge remote-tracking branch 'origin/main' into per-page-styles
117
![](/Customization/custom-fancyblock.png)
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
118
## Styling individual pages or categories
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
126
### Target a Specific Page
127
e14230 Freddy Heppell 2026-01-16 01:32:44
Small wording update
128
Hides the sidebar on the homepage.
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
136
### Style all pages in a category
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
147
### Style a Category Index
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
}
160
```