Ideas for contribution

[deseven]

@redimp

I have some ideas that I'm personally interested to work on, but not sure you'd like to see as a part of the project, so if you have time someday please evaluate the following. Not urgent :)

1. Add customHead.htm and customBody.htm, in addition to custom.js/custom.css. Would be useful for inserting additional resources and external scripts, such as Google Analytics. Custom head and body html from files #326

2. Menu improvements - allow to add separators and define icons for each entry. For icons, we could simply permit stating custom classes, so the included font-awesome could be used, or pretty much any other icon font. I currently implemented it for my wiki via custom.js, but this is quite hacky and a proper solution would be much better. Menu improvements #325
   

3. Do not load Mermaid and MathJax unless needed (required to render the page). This will shave off 2.7 and 0.8MB (0.9 and 0.2MB gzipped) respectfully, which is more than a half of the initial download size. Optimized resource loading #323

4. Redirect /Home to / and /Page/ to /Page (or vice versa), since these could be treated as different pages and hurt search results (see explanation here for example). An alternative to this is to use <link rel="canonical">. This is not that big of a deal like it was 10 years ago, but it's a simple fix to implement just in case. Canonical urls & meta description #324

5. Add <meta name="description">. I see "Site Description" in the Settings that claims to do so, but it doesn't. Canonical urls & meta description #324

[redimp]

Hey @deseven, thanks for posting this!

1. For sure a useful idea. For now adding this as static files like the custom.js and custom.css are handled would be preferred. (For the sake of completeness: I'm thinking about adding a feature that the Admin role can edit cutom.css/js/htmls and these are stored in the repository. This is inspired by the feat: custom stylesheet management #298, but I would prefer to not save the custom files as normal wiki pages).
2. Another cool feature. Please make use of the SIDEBAR_CUSTOM_MENU so that it's backwards compatible. e.g. add an "icon" to the json object, e.g. {"link": "/-/help", "title":"User Guide", "icon":"<i class="fas fa-question-circle"></i>" }
3. Yes! Please make sure to always load the libraries in the editors preview and the documenation ;)
4. Alright.
5. Yes, please.

[deseven]

@redimp thank you for your comments and approvals!

1. What would your plan for upgrading be after that? Some sort of an automated migration that would pick the existing custom code from the static files to put it in the repo?

No comments on other stuff, agreed.

[redimp]

1. What would your plan for upgrading be after that? Some sort of an automated migration that would pick the existing custom code from the static files to put it in the repo?

Hm, I think it would be best of all the options co-exist. User can have the option of adding static (html, js, css) files and/or dynamically configure (html, js, css) files that are stored in the repo. The overhead if something is not used is so minimal I think it will not do any harm.

[deseven]

I found undocumented (correct me if I'm wrong) HTML_EXTRA_HEAD and HTML_EXTRA_BODY in server.py, which do exactly what I planned, although I imagine it could be pretty inconvenient to add html via env vars.

I see several options:

1. Leave them be and add new functionality to read customHead.htm and customBody.htm that would work in parallel.
2. Leave them be and add new functionality to read customHead.htm and customBody.htm, but env vars would have priority (don't read files if they are defined).
3. Remove them.

What do you think?

[redimp]

Uhm, I must admit, I completely forgot I added these. Please (1) leave them be and add the new functionality. I will update the documentation now.

[deseven]

I'm going to update the docs to reflect the custom html loading anyway, I could also mention these env vars if that works for you.

[redimp]

Done it for now, please do not hesitate to improve this: https://otterwiki.com/Customization#tweaking-the-html-head-and-body

[deseven]

I don't have any ideas on improvements, looks great as it is now :) I'll just extend it later.

[deseven]

Actually ended up with restructuring it into two main sections, I think this should be a bit more clear.

[redimp]

Will review (and merge) your PRs over the weekend. From the first look everything looks great!

[redimp]

With everything merged I will do some testing and make a release tomorrow. Demo running on https://testing.otterwiki.com/.

[deseven]

I see some 500 errors when requesting page preview in the testing copy, but I can't reproduce it with current main on my local instance. Could you look at the error?

[deseven]

Here's the request:

curl 'https://testing.otterwiki.com/123/preview' \
  -X POST \
  -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0' \
  -H 'Accept: */*' \
  -H 'Accept-Language: en-GB,en;q=0.8,en-US;q=0.7,ru;q=0.5,sr;q=0.3,hr;q=0.2' \
  -H 'Accept-Encoding: gzip, deflate, br, zstd' \
  -H 'Referer: https://testing.otterwiki.com/123/edit' \
  -H 'Content-Type: multipart/form-data; boundary=----geckoformboundary156d590767c3a0844674ece83687b2b7' \
  -H 'Origin: https://testing.otterwiki.com' \
  -H 'DNT: 1' \
  -H 'Connection: keep-alive' \
  -H 'Cookie: halfmoon_preferredMode=dark-mode; session=.eJxFj81qAzEMhF9l8SWXQvwjy84-QGgPPZQeSwn-kZKF7KbY61Ppu1eHQk8afYPEzLe6cKN-U_PeBj2py1LVrAyEgmxNrlwzM-RYfQ6MTKgxB4TqkrMuG-G2UvLIAN5mC8CRrLOYAdCk6HQ8ccngqo6xouFQfPEnEiOwB689edYyko5Y2FSBEY2SIKNT-0sj61e6UmljzV3NH-ql90H9eHhftuudprfx2OkwLdt0Xu60pZW6nJwp7UO6HV-prUk-_SORz4-V1OfPL4ckTTE.aT1x6Q.eI7I2Dx32w0PT4xf6zWRQuc6s8I; remember_token=1|e846be9074fb705640accdf67d4669ddc81b0829f5e656f0303015b08abec38e6685358da1802b4a8e2e97a82bbbbb8f188b3d5611c4741bca24f59374febcd4' \
  -H 'Sec-Fetch-Dest: empty' \
  -H 'Sec-Fetch-Mode: cors' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'Priority: u=0' \
  -H 'Pragma: no-cache' \
  -H 'Cache-Control: no-cache' \
  -H 'TE: trailers' \
  --data-binary \
  $'------geckoformboundary156d590767c3a0844674ece83687b2b7\r\nContent-Disposition: form-data; name="content"\r\n\r\n# Customization\r\n\r\n## Customizing Your Copy of the Wiki\r\n\r\nAn 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.\r\n\r\nThere are currently two ways to customize the wiki:\r\n- Using `custom` directory to be able to add custom CSS, JS and HTML \r\n- Using env variables for small HTML tweaks\r\n\r\nBoth methods work independently of each other.\r\n\r\n### Using `custom` Directory\r\n\r\nThe template automatically loads several custom files which are empty by default. You can mount a directory into the container to provide the following customizations:\r\n- `custom.css` - custom CSS styles (from version **2.3.1**)\r\n- `custom.js` - custom JavaScript (from version **2.3.1**)\r\n- `customHead.html` - custom HTML injected into the `<head>` section (from version **2.14.5**)\r\n- `customBody.html` - custom HTML injected into the `<body>` section (from version **2.14.5**)\r\n\r\nFor example, with a `docker-compose.yaml` like this:  \r\n```yaml\r\nversion: \'3\'\r\nservices:\r\n  otterwiki:\r\n    image: redimp/otterwiki:2\r\n    restart: unless-stopped\r\n    ports:\r\n      - 8080:80\r\n    volumes:\r\n      - ./app-data:/app-data\r\n      # a custom local directory with a custom.css, custom.js, customHead.html and customBody.html\r\n      - ./custom:/app/otterwiki/static/custom\r\n```\r\n\r\n> [\041NOTE]\r\n> 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\r\n\r\n### Using Environment Variables to Tweak HTML\r\n\r\nThe HTML body and head of every html rendered can be tweaked via `HTML_EXTRA_HEAD` and `HTML_EXTRA_BODY` environment variables.\r\n\r\nThis can be used for small tweaks that don\'t require big amounts of code.\r\n\r\n\r\n## Examples\r\n\r\nIf 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.\r\n\r\nCheck [otterwiki/docs/custom_css_example](https://github.com/redimp/otterwiki/tree/main/docs/custom_css_example) on github for ready-to-test examples.\r\n\r\n### Serif Pages\r\n\r\nThis is an example `custom.css` that uses the serif font\r\n`Baskervville` for the content rendered in the page.\r\n\r\n```css\r\n@import url(\'https://fonts.googleapis.com/css2?family=Baskervville\');\r\n\r\n.content > .page {\r\n    font-family: \'Baskervville\', serif;\r\n    font-weight: 400;\r\n}\r\n```\r\n\r\n\041[](/Customization/a/baskervville-page.png)\r\n\r\n### Adding the "Fork me on github" ribbon\r\n\r\nThis is an example of adding the "Fork me on github" ribbon using env variables for custom HTML.\r\n\r\n```yaml\r\nservices:\r\n  otterwiki:\r\n    image: redimp/otterwiki:2\r\n    restart: unless-stopped\r\n    ports:\r\n        - 8080:80\r\n    environment:\r\n      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" />\r\n      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>\r\n    volumes:\r\n      - ./app-data:/app-data\r\n```\r\n------geckoformboundary156d590767c3a0844674ece83687b2b7\r\nContent-Disposition: form-data; name="cursor_line"\r\n\r\n0\r\n------geckoformboundary156d590767c3a0844674ece83687b2b7\r\nContent-Disposition: form-data; name="cursor_ch"\r\n\r\n0\r\n------geckoformboundary156d590767c3a0844674ece83687b2b7--\r\n'

[redimp]

The logs showed an error in mistune .. was not able to reproduce it and ended up with rebuilding the image. Works for me now.

The images are

• redimp/otterwiki:dev-test-all-slim
• redimp/otterwiki:dev-test-all

[deseven]

Yeah, works fine now... Weird.

[deseven]

Alright, everything is merged and released, thank you for your patience and your time to make it happen, I'll think about more contributions in the future, maybe something from existing issues :)