Document themes (#48)

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:
 

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.

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.

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.