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
89
## Styling individual pages or categories
90
91
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.
92
93
The path is turned into a slug in each section, for example _My Category/My Page_ becomes `my-category/my-page`.
94
95
These are some examples of potential style customisations:
96
97
### Target a Specific Page
98
e14230 Freddy Heppell 2026-01-16 01:32:44
Small wording update
99
Hides the sidebar on the homepage.
a2a824 Freddy Heppell 2026-01-16 01:29:29
Add a few examples of data atts
100
101
```css
102
body[data-page-path="home"] .extra-nav {
103
display: none;
104
}
105
```
106
107
### Style all pages in a category
108
109
Applies a different colour to pages in _My Category_.
110
111
```css
112
body[data-page-path^="my-category/"] h1 {
113
color: darkred;
114
font-weight: bold;
115
}
116
```
117
118
### Style a Category Index
119
e14230 Freddy Heppell 2026-01-16 01:32:44
Small wording update
120
> [!NOTE]
121
> The whole wiki page index has a `data-index-path` of `/`
122
123
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
124
125
```css
126
/* body[data-index-path^="my-category/"]
127
to apply to subcategories as well*/
128
body[data-index-path="my-category"] .pageindex-columns {
129
columns: 1
130
}
131
```