Customization - blame None

Blame

378010	Ralph Thesen	2025-12-12 22:58:48
Added documentation for HTML_EXTRA_HEAD and HTML_EXTRA_BODY

# Customization

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

## Customizing Your Copy of the Wiki

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

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

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

There are currently two ways to customize the wiki:

- Using `custom` directory to be able to add custom CSS, JS and HTML 

- Using env variables for small HTML tweaks

Both methods work independently of each other.

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

### Using `custom` Directory

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

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:

- `custom.css` - custom CSS styles (from version **2.3.1**)

- `custom.js` - custom JavaScript (from version **2.3.1**)

- `customHead.html` - custom HTML injected into the `<head>` section (from version **2.15.0**)

- `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

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

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

```yaml

version: '3'

services:

  otterwiki:

    image: redimp/otterwiki:2

    restart: unless-stopped

    ports:

      - 8080:80

    volumes:

      - ./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

      # 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

      - ./custom:/app/otterwiki/static/custom

```

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

> [!NOTE]

> 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

### Using Environment Variables to Tweak HTML

The HTML body and head of every html rendered can be tweaked via `HTML_EXTRA_HEAD` and `HTML_EXTRA_BODY` environment variables.

This can be used for small tweaks that don't require big amounts of code.

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

## Examples

b59643	Ralph Thesen	2024-03-23 14:47:34
added how-to on customize the otterwiki theme

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

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.

Check [otterwiki/docs/custom_css_example](https://github.com/redimp/otterwiki/tree/main/docs/custom_css_example) on github for ready-to-test examples.

### Serif Pages

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

`Baskervville` for the content rendered in the page.

```css

@import url('https://fonts.googleapis.com/css2?family=Baskervville');

.content > .page {

    font-family: 'Baskervville', serif;

    font-weight: 400;

}

```

2e88a6	Ralph Thesen	2024-03-23 23:06:53
reorganized customization

![](/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

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

### 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

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

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

```yaml

services:

  otterwiki:

    image: redimp/otterwiki:2

    restart: unless-stopped

    ports:

        - 8080:80

    environment:

      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" />

      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>

    volumes:

      - ./app-data:/app-data

```

![](/Customization/github-ribbon.jpg)

1968a6	Freddy Heppell	2026-01-13 22:12:44
Document custom fancyblocks

### Custom Fancy Block Styles

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`.

```md

::: extradanger

## Watch Out!

This Fancy Block has custom styles

:::

```

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

117

![](/Customization/custom-fancyblock.png)