Custom Theming

[brheinfelder]

Hi there! Really enjoying Otter Wiki! I was wanting to do some custom theming for my wiki and wondered if there was a way to modify the CSS in the docker container? I tried to find the path to mount based on the docker entry point file, but couldn't seem to find the right path for the static files.

[redimp]

Hey @Futureless671, thanks for opening up this request.

Currently you could just replace the otterwiki.css with a local file via

version: '3'
services:
  otterwiki:
    image: redimp/otterwiki:2
    ports:
      - "8080:80"
    volumes:
      # mount the local custom.css
      -  ./otterwiki.css:/app/otterwiki/static/css/otterwiki.css
    ...

But you would have to manually apply the changes made to the otterwiki.css, which would be annoying.

I have an idea to make tweaks better maintainable: With a folder /app/otterwiki/static/custom added two the image, that contains by default two empty files: custom.css and custom.js that will be loaded in the layout.html template, it would be easy to tweak the otterwiki themes in local deployments.

What do you think? Or anyone who needs tweaking the themes.

[brheinfelder]

Personally I would prefer a solution that gave me full control of all the static files. That said, I have very limited development experience with Flask so I'm probably not the best person to make recommendations about best/common practice. If there is not a good solution that gives access to all the static files, then it seems to me that your proposal would be reasonable.

For anyone that happens to be looking for a partial solution in the meantime, I've had great success so far using html with inline css to extend the theming. However that still lacks the ability to override the default classes.

[redimp]

When running the docker image, not flask serving the static files, the nginx is responsible for that (this is what is recommended for performance). Luckily you can control of the static files are served by setting the environment variable STATIC_PATH, which defaults to /app/otterwiki/static see docker/entrypoint.sh

[brheinfelder]

Ah, I see. In that case, there should be no issue updating static files, right? Would maybe require disabling caching on nginx to avoid annoyance, but aside from that. I think the main issue here is that mounting a volume in docker overrides the content in the container path, so the static files aren't really externally accessible. Would it be possible to host the static files in some auxiliary folder to begin with and then copy those files over to a known location after volumes have been mounted? That way all static files are externally accessible and you don't need to worry about what will be easiest to maintain because everyone can just do whatever they feel like.

Also my wiki isn't super important so I'm happy to help test whatever solution you come up with if you need.

[brheinfelder]

Hmmm... Well I managed to expose the static files for editing but changes and overrides seem to have no effect, even after a container restart. I have checked to make sure the changes are persistent across container restarts/rebuilds, but the website never seems to update even after clearing cache. Maybe this will not be as simple as I thought. I will keep trying.

[redimp]

I just pushed 30f62f5. Will include this in the next release 2.3.1. You can find an example how to use this feature here docs/custom_css_example, the mentioned documentation is not online yet, though.

[brheinfelder]

Can't seem to get this to work. Pulled a fresh docker image, updated my compose file to include the new custom mount point. Folder mounts without any contents. Adding the custom.css file manually and using the included baskerville example yields no changes. Have restarted container, have cleared browser cache.

[redimp]

Hey @Futureless671 have you tested if the baskerville example works for you?

I've just pushed 2c42cef where I updated the docker-compose.yaml.

Can you start this and check if it works as expected?

If yes, please check if you can add ypur changes to the custom.css and if ypu can see them in http://localhost:8080/static/custom/custom.css

[brheinfelder]

Still cant get it to work. My docker-compose file is as follows:

version: '3'
services:
  web:
    build: ../..
    image: redimp/otterwiki:2
    restart: unless-stopped
    ports:
      # forward the http port to 8080
      - "8085:80"
    volumes:
      # mount the local custom.css
      -  ./custom:/app/otterwiki/static/custom:ro
      - ./app-data:/app-data

When bringing this container up, the 'custom' directory is created and mounted, but it's empty. I Manually created custom.css with the following contents:

/*
 * This is an example custom.css that uses the serif font
 * Baskervville for the content rendered in the page.
 */

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

.content > .page {
    font-family: 'Baskervville', serif;
    font-weight: 400;
}

My site shows no theming changes after a container restart. The contents of the file at http://localhost:8085/static/custom/custom.css are what I'm guessing is the intended default custom.css contents:

/*
* custom.css
 *
 * This file is loaded via the layout.html template in every
 * page of an Otter Wiki.
 *
 * see https://otterwiki.com/Customization for examples.
 *
*/

Seems to me like there is some weirdness going on with the docker volume

[redimp]

Well, you create the directory custom first, add the file custom/custom.css and then run docker-compose up. Then the file is available in the container.

Have you cloned the github repository and tried the exact example?

I've just tested it successfully under MacOS (arm64, Docker version 25.0.3), Debian 12 (amd64, Docker version 24.0.7) and raspian (armv6, Docker version 20.10.2).

[brheinfelder]

To clarify, do I need to manually build from the repo for now because it's a dev build? I'm a bit confused by your instructions because I would have assumed that the docker compose would override anything built from source since the container image is specified there? Apologies for all the questions

[redimp]

Sorry, it was not my intention to confuse you.

No need for a dev build, since you are getting the correct (empty) custom.css we know that you've got the correct image version.

My intention was to make sure that at least the example (as is) works.

[brheinfelder]

Sorry I haven't responded to this, life stuff. I just sat down to try to get this working again, opened my wiki and lo and behold, the theming seems to be applied. Nothing has changed since the last time I worked on it, it's just been sitting. Not sure what made the difference, but changes I make are now reflected on my wiki. Thanks for the help!

[redimp]

Good to hear! I'm glad it worked out.