Implement and document styles customization

[umputun]

We should have a way to define external CSS for basic customizations - things like link colors, font sizes, and other styles.

On compose level this will be as simple as some volume mapping, like - ./etc/styles.css:/srv/web/styles.css

Also, need instructions in the readme on how to do it and what we allow to customize (with an example)

[nocturnal-dimensions]

why can't there be just .css files inside the ./var directory, including the ones with the default themes?

[umputun]

@akellbl4 & @Mavrin -it will be very nice if we finally could support custom css somehow. Pls share your brilliant ideas

[ColasNahaboo]

A simple solution could be to add en env var CSS in docker-compose.yml that can have as value an additional CSS to use. The overriding will be left to the CSS natural cascading rules. The documentation should then tell which CSS selectors should stay invariant between remark42 releases.

- CSS=https://my-local-css-url.css

Edit: the following does not work, as it messes a bit too much with authentication. For it to work, you should also proxy /auth/ and re-declare your main site to all the OAuth provided instead of the remark42 site. Not worth the trouble for just styling in my case.

On my apache web server in the meantime I have made this code that works currently, with the hack that I have proxied the urls /web/ and /api/ to my local server remark42 as it it was on the same domain (otherwise modern browsers wont let you inject a CSS link into remark42 iframe contents):

I added some code to the client-side javascript added to pages (after the line /* Add my custom CSS */) that use a new js config field css

It is usable now but of course it is not a general solution as it supposes the urls /web/ and /api/ are free to use on the host server. The %-vars are variables provided by my host site, a Foswiki engine.

<script>
  var remark_config = {
    host: "https://%HTTP_HOST%",    /* will be proxied to the remark42 server */
    site_id: '%WIKITOOLNAME%',
    components: ['embed', 'last-comments', 'counter'],
    url: '%SCRIPTURL{"view" topic="%BASEWEB%.%BASETOPIC%"}%',
    css: 'https://%HTTP_HOST%/pub/Main/SiteStyle/colas_remark42.css'
};
 (function(c) {
    for(var i = 0; i < c.length; i++){
      var d = document, s = d.createElement('script');
      s.src = remark_config.host + '/web/' +c[i] +'.js';
      s.defer = true;
      (d.head || d.body).appendChild(s);
    }
    /* Add my custom CSS */
    window.onload = function(){   
      var f = document.querySelector("div#remark42 > iframe");
      var d = f.contentDocument? f.contentDocument: f.contentWindow.document;
      var h = d.getElementsByTagName("head")[0];
      var s = document.createElement('link');
      s.type = 'text/css';
      s.href = remark_config.css;
      s.rel = "stylesheet";
      h.appendChild(s);
    };
  })(remark_config.components || ['embed']);
</script>

[ColasNahaboo]

And.. I missed the obvious, simple solution: If you access your remark42 server via a proxy, just redirect in the proxy the urls:

• /web/last-comments.css
• /web/remark.css
  to your own CSS files, that can be either a copy of the distributed ones that you modify, or better that only define modifications, and @import the original ones via a proxy route, such as:

@import '/web-orig/remark.css'
... your CSS additional code

With the proxy configured to redirect /web-orig/ to remark42 ```/web/`` urls

For my apache proxy, this means:

  ProxyRequests Off
  ProxyPass "/web/last-comments.css" "!"
  ProxyPass "/web/remark.css" "!"
  ProxyPass        /web-orig/  http://127.0.0.1:8080/web/
  ProxyPassReverse /web-orig/  http://127.0.0.1:8080/web/
  ProxyPass        /  http://127.0.0.1:8080/
  ProxyPassReverse /  http://127.0.0.1:8080/
  <Proxy *>
    Require all granted
  </Proxy>

The css are thus excluded from the proxying (the "!") and are served as local files in the proxy root dir, and they contain my customizations and the lines
@import '/web-orig/remark.css';

[ColasNahaboo]

A simple solution could be to add en env var CSS in docker-compose.yml that can have as value an additional CSS to use. The overriding will be left to the CSS natural cascading rules. The documentation should then tell which CSS selectors should stay invariant between remark42 releases.

- CSS=https://my-local-css-url.css

Mmm, this is not sufficient. We should also be able to specify a different CSS for each SITE. Maybe with an additional variable SITES_CSS containing a comma-separated list of space-separated pairs of site and their css url?

e.g.:
- SITES_CSS=https://my.site.one https://my.site/one.css, https://my.site.two https://my.site/two.css

[Mavrin]

@ColasNahaboo could you attach your overridden css. It is interesting, what is real user want to customize? Maybe we can provide more reliable and convenient api. And also what do you think about follow approach #599 (comment)?

[ColasNahaboo]

I am in the process of totally redesigning my web site, and remark42 will be used on the new version, so I am not fixed yet on what I wanted to customize, so for now I just wanted to see if it was possible.

Here its current state, mainly to make the fonts consistent with the rest of the site:

@import "/web-orig/remark.css";

/* my customizations */

/* styling inside the remark42 iframe */
div#remark42 div.root .comment {
  font-size:13px;
  font-family: Roboto, Verdana, helvetica, Arial, Verdana, Georgia, Geneva, sans-serif;
  line-height: 19px;
}
div#remark42 div.root,
div#remark42 textarea.comment-form__field {
  font-size:14px;
  font-family: Roboto, Verdana, helvetica, Arial, Verdana, Georgia, Geneva, sans-serif;
  line-height: 21px;
}

[ColasNahaboo]

On #599, I like the idea of specifying the customization with a field of remark_config, but I think the theme approach is overboard. In my opinion you are going a route that are making you reinvent the wheel of all the work that has been done in CSS and the various CSS processors (sass, less, ...) and tools (editors, validators, ...). And it is very hard to anticipate what people will want to customize.

Just let people provide their CSS, (that can be a provided "theme") with a option to either replace or add to the built-in CSS.

remark42 is an ancillary technology that is to be used on web sites that already use some conventions or framework to manage colors and styles. In my opinion, just accepting standard CSS is the best way to ease integration, otherwise you run the risk of having people struggle to provide the info in some remark42 specific formalism instead of just plain CSS.

[sattellite]

Colors in custom properties is good solution for theming. But use styles from CSS from parent site is impossible for the remark42 customization because it is inside iframe.
It is best to implement the ability to connect additional CSS files as previously suggested in this issue.

[mind-overflow]

Yes, providing custom CSS sounds like the easiest way, both for you developers and for users who just want to customize the theme. To prevent users from using outdated CSS files in future versions, however, what I suggest is some sort of "put your additional CSS in this file and we will auto-import the rest" or some kind of versioning scheme (like in a subfolder, /css/1.0/remark.css).

If we have to consider supporting different websites on the same instance too, as @ColasNahaboo, you could, again, add the domain to the css path:

/var/css/comments.site1.com/1.0/remark.css
/var/css/comments.site2.com/1.0/remark.css

or, by valuing version before domain:

/var/css/1.0/comments.site1.com/remark.css
/var/css/1.0/comments.site2.com/remark.css

Either way, there are plenty of viable and perfectly fine ways to implement this, so I really hope it won't be particularly difficult to do! And thanks for the awesome project you're bringing to all of us :)

[mind-overflow]

Hey! No update on this?

[akellbl4]

@mind-overflow we are working on a few different features now, they are relative to this. We will try to add this feature as a beta in the near future.

[mind-overflow]

@mind-overflow we are working on a few different features now, they are relative to this. We will try to add this feature as a beta in the near future.

Oh, ok - that's great news! I was gonna fork the repo and try to implement this myself, but if you're already working on related features, I don't want to take the risk of making something that may or may not be compatible (or redundant) with those upcoming things.

Thanks for the awesome work!

[akellbl4]

@mind-overflow yep, sure. I'll write if smth changes. Thanks ;)

[akellbl4]

While developing the new auth form I added permanent class names on that part of the interface and it could be customized. The next step is to provide the ability to connect third-party CSS file for styles customization.

[maxmastalerz]

I just wrote up a short blog post on how to customize the css via the proxy workaround discussed here. It contains a solution for proxying with Nginx(vs Apache): https://maxmastalerz.com/blog/how-to-customize-remark42-css-via-a-proxy-workaround

[JeppeKlitgaard]

I am also currently having to resort to a reverse-proxy approach to delivering custom CSS. It would be fantastic if it was possible to inject some custom CSS overrides using a docker volume mount or something similar! Thanks for all your great work on remark42!

The reverse-proxy approach is hard to make work nicely with a local development environment.