From 5be530d7b69feba74b9f3110e14127d6a0c5e36f Mon Sep 17 00:00:00 2001 From: Ana Gelez Date: Fri, 15 Nov 2019 20:09:22 +0100 Subject: [PATCH] Document themes (#48) --- source/environment.html.md | 1 + source/guide/creating-themes.html.md | 62 ++++++++++++++++++++ source/guide/instance-administration.html.md | 20 +++++++ source/guide/manage-a-blog.html.md | 13 ++++ 4 files changed, 96 insertions(+) create mode 100644 source/guide/creating-themes.html.md create mode 100644 source/guide/instance-administration.html.md create mode 100644 source/guide/manage-a-blog.html.md diff --git a/source/environment.html.md b/source/environment.html.md index 036072d..95eb68c 100644 --- a/source/environment.html.md +++ b/source/environment.html.md @@ -19,6 +19,7 @@ Here are the variables that Plume uses: meaning that all your users will get disconnected. You can generate one with `openssl rand -base64 32`. - `SEARCH_INDEX`: the directory where the search index will be saved (`search_index` by default). - `MEDIA_UPLOAD_DIRECTORY`: the directory in which to store the uploaded medias (`./static/media` by default). Plume won't create this directory if it doesn't exist, so make sure to create it before. +- `DEFAULT_THEME`: the name of the default theme. It should be the same as the name of the directory containing the theme in `static/css`. The SMTP server to send mails can be configured with: diff --git a/source/guide/creating-themes.html.md b/source/guide/creating-themes.html.md new file mode 100644 index 0000000..102c383 --- /dev/null +++ b/source/guide/creating-themes.html.md @@ -0,0 +1,62 @@ +--- +title: Creating a theme +icon: file-plus +summary: Tips for people who want to create a theme for an instance +--- + +Plume themes are CSS files (and optionally other resources that can be loaded with CSS, like fonts or background images), +so all you need to know to write a theme is to know CSS. + +# Base template + +A good start can be the official base theme, that is written in SCSS, and that you can find +[in Plume's repository](https://github.com/Plume-org/Plume/tree/master/assets/themes/default). +You can copy these files (they are under the AGPL-3.0 license), and start by changing the variables +in `_variables.scss`. If you use this theme as a basis, the [SASS/SCSS](https://sass-lang.com/) will be +needed to transform it to a single CSS file that an admin can install on their instance. + +To test your theme, you can install a browser extension like [*Stylish*](https://userstyles.org) and copy your CSS inside. + +Plume updates may sometimes break your theme (if we make a layout change, add a new CSS class, or so on). +If you want to ensure your theme continues to work as Plume is developed, following [the project on GitHub](https://github.com/Plume-org/Plume/) can notify you when we make changes that might affect your theme. +Pull requests and commits breaking themes are normally clearly identified as such. + +# Detailed explanations + +There are two kind of themes in Plume: + +- instance themes, that an admin can define as the default theme for an instance, and that users registered on this instance can choose as their personnal default if they want. +- and blog themes, that blog authors can use to customize their blogs. They are only applied to the pages of this blog, and override instance-level themes. + +The only difference when you build a theme is that blog themes should be in the `static/css/blog-NAME` directory, whereas instance themes should be in `static/css/NAME` (with `NAME` the actual name of your theme). + +Inside of this directory, the only required file is `theme.css`. +This file is the only one that Plume loads, so it is in charge of loading everything else (fonts that you use for instance). + +And that's it, you are free to do anything you want with themes, as long as you respect these rules. + +# Detecting dark themes + +When writing theme for blogs, it can be usefull to know if the global instance theme is dark or not, to adapt the blog's theme accordingly. +Thus, as a convention, dark themes should always have the word "dark" in their name. +Plume then adds the current theme name to the CSS classes of the HTML document, allowing you to detect which kind of theme the user has. + +Here is an example that shows quotes in blue for ligth themes, and in orange for dark themes: + +```css +article blockquote { + color: blue; +} + +html[class*=dark] article blockquote { + color: orange; +} +``` + +# Plume can compile your themes + +If you build Plume from source, any theme in `assets/themes/NAME` will be compiled in `static/css/NAME`. +SCSS or SASS file will be transformed into CSS, unless their name start with an underscore. +Each SCSS/SASS file is treated as a different theme even if they are in the same directory, allowing them to share files (usefull when you want to do color variants of your theme for example). + +Other files will just be copied to the output directory. diff --git a/source/guide/instance-administration.html.md b/source/guide/instance-administration.html.md new file mode 100644 index 0000000..c76bf2e --- /dev/null +++ b/source/guide/instance-administration.html.md @@ -0,0 +1,20 @@ +--- +title: Instance administration +icon: settings +summary: A guide for instance administrators +--- + +# Managing themes + +There are two kind of themes in Plume: + +- instance themes, that an admin can define as the default theme for an instance, and that users registered on this instance can choose as their personnal default if they want. +- and blog themes, that blog authors can use to customize their blogs. They are only applied to the pages of this blog, and override instance-level themes. + +As an admin, you are in charge of choosing which themes (both instance-level and blog-level ones) will be available on your instance. +To make a theme available, all you have to do is to put its files in `static/css/NAME` (with `NAME` the actual name of the theme). + +If you build Plume from source, any theme in `assets/themes/NAME` will be compiled in `static/css/NAME`. +You can thus download the source of a theme written in SCSS or in SASS and build it along with Plume (just with `cargo run`, `cargo build` or `cargo install`, as usual). + +You can also choose the default instance theme with the `DEFAULT_THEME` environment variable. diff --git a/source/guide/manage-a-blog.html.md b/source/guide/manage-a-blog.html.md new file mode 100644 index 0000000..da07af6 --- /dev/null +++ b/source/guide/manage-a-blog.html.md @@ -0,0 +1,13 @@ +--- +title: Manage a blog +icon: book-open +summary: 'How to customize your blog' +--- + +You can open your blog settings, by clicking on the "Edit" button in the top right part of its main page. + +# Adding a custom theme + +In your blog settings, you will have a dropdown menu that will let you select your theme. + +Please note that blog themes are not federated, so only people reading you on your instance will see them.