| `COMMIT_MESSAGE` | `'REQUIRED'` | set `COMMIT_MESSAGE='OPTIONAL'` if commit messages are optional |
-
| `RETAIN_PAGE_NAME_CASE` | `False` | set `RETAIN_PAGE_NAME_CASE=True` to
-
| `GIT_WEB_SERVER` | `False` | Set to to true to allow cloning the wiki via git+http(s) |
+
| `COMMIT_MESSAGE` | `'REQUIRED'` | set to `'OPTIONAL'` if commit messages should be optional |
+
| `RETAIN_PAGE_NAME_CASE` | `False` | set to `True` to retain case of the page name in the filename used for storing the page |
+
| `TREAT_UNDERSCORE_AS_SPACE_FOR_TITLES` | `False` | set to `True` to replace underscores (_) with spaces in page titles, breadcrumbs, and page index |
+
| `GIT_WEB_SERVER` | `False` | Set to to `True` to allow cloning the wiki via git+http(s) |
| `MAX_FORM_MEMORY_SIZE` | `1000000` | The the maximum size of a submitted form, see the [Flask documentation](https://flask.palletsprojects.com/en/stable/config/#MAX_FORM_MEMORY_SIZE). Increase this if you have really large pages to edit and save. |
### Mail configuration
customization.md ..
@@ 1,17 1,25 @@
# Customization
-
## Theme Customization
-
An Otter Wiki was not designed with the idea that user-defined topics might become necessary. However, since there is a need, a way to modify the theme has been added.
+
## Customizing Your Copy of the Wiki
-
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.
+
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.
-
Check [otterwiki/docs/custom_css_example](https://github.com/redimp/otterwiki/tree/main/docs/custom_css_example) on github for ready-to-test examples.
+
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.
-
### `custom directory`
+
### Using `custom` Directory
-
With version **2.3.1** the template loads a `custom.css` and a `custom.js` which are empty by default. You can mount the directory into the container, for example with a `docker-compose.yaml` like this:
+
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**)
+
For example, with a `docker-compose.yaml` like this:
```yaml
version: '3'
services:
@@ 22,15 30,29 @@
- 8080:80
volumes:
- ./app-data:/app-data
-
# a custom local directory with a custom.css and a custom.js
+
# a custom local directory with a custom.css, custom.js, customHead.html and customBody.html
- ./custom:/app/otterwiki/static/custom
```
-
### Examples
+
> [!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.
+
-
#### Serif Pages
+
## Examples
-
This is an example custom.css that uses the serif font
+
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
`Baskervville` for the content rendered in the page.
```css
@@ 44,14 66,9 @@
-
> [!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
-
-
## Tweaking the HTML head and body
-
-
The HTML body and head of every html rendered can be tweaked via `HTML_EXTRA_HEAD` and `HTML_EXTRA_BODY`.
+
### Adding the "Fork me on github" ribbon
-
This can be used for small tweaks, e.g. adding the "Fork me on github" ribbon:
+
This is an example of adding the "Fork me on github" ribbon using env variables for custom HTML.
