Pepperminty-Wiki/docs/06.7-Custom-Themes.md

# Custom Themes
CSS in Pepperminty Wiki is managed by 2 principle settings:

Setting			| Meaning
----------------|--------------------------------------------------------------
`css`			| The current CSS that should be applied (or the keyword `auto` to signal that the automatic default inbuilt theme should be used instead)
`css_custom`	| Any additional CSS that should be applied.

Both of these setting also  support a URL instead - in which case a `<link rel="stylesheet" />` will be generated.

Pepperminty Wiki _also_ has a theme gallery system, which can be enabled by including the `feature-theme-gallery` module. This is managed by another handful of settings:

 - `css_theme_autoupdate_url`
 - `css_theme_autoupdate_interval`
 - `css_theme_gallery_index_url`

The most important one you'll probably be interested in is `css_theme_gallery_index_url`,  which should be a space-separated list of URLs that each point to a theme index file. Said theme index files can contain any number of theme definitions. Once specified, the theme  gallery can be accessed through a link in the master wiki settings - or directly via the `theme-gallery` action.

Note that the theme gallery obviously needs to make 1 or more external HTTP/S requests in order to function. To this end, a warning message is displayed when you visit the theme gallery to make sure that you're ok with this.


## Hosting your own theme gallery
Although you are welcome to submit your own theme to Pepperminty Wiki's official repository and default theme gallery via a pull request, hosting your own theme gallery is really quite simple. First, you need a theme index JSON file that looks something like this:

```json
[
	{
		"hash": "f2b4c237020e8663f5a4ff6d29a73eaf2bb431d8c82749244a6752467a16f9ce",
		"id": "none",
		"name": "No theme",
		"description": "A special theme with no CSS. Useful if you want to create your own theme from scratch!",
		"author": "Starbeamrainbowlabs",
		"author_link": "https://starbeamrainbowlabs.com/",
		"minversion": "v0.20"
	},
	{
		"hash": "8841461af4c79d365c5792ba3b93e4fae30bed7574d875e1540539f4ec961c8c",
		"id": "default",
		"name": "Default",
		"description": "The default theme.",
		"author": "Starbeamrainbowlabs",
		"author_link": "https://starbeamrainbowlabs.com/",
		"minversion": "v0.20"
	},
	{
		"hash": "071871fdc91cbcb13ca26bb853dbe32ee36e92a7ae69b9fd51f9a93cc37df8c0",
		"id": "blue",
		"name": "Blue",
		"description": "A more blue theme.",
		"author": "ZestyclosePainting",
		"author_link": "https://reddit.com/u/ZestyclosePainting",
		"minversion": "v0.20"
	}
]
```

Each theme present in the gallery should be an object in a top-level array. The 7 keys are as follows:

Key		| Meaning
--------|--------------------
`hash`	| The SHA256 hash of the theme file itself.
`id`	| The id of the theme. No spaces and only lowercase alphanumeric characters + dashes please.
`name`	| The display name for the theme. Put anything you like here, but it doesn't support HTML.
`description`	| A sentence or 2 describing the theme.
`author`		| The name of the author
`author_link`	| A link to the author's website homepage / social media.
`minversion`	| The minimum version of Pepperminty Wiki required to run the theme.

Each theme should be in a subfolder alongside the main theme index file with the name corresponding to the theme's id. The theme CSS should be in a file called `theme.css` inside this folder, and the preview images should have the names `preview_small.png` (displayed by default) and `preview_large.png` (displayed when you click on the small preview). Example:

 - themeindex.json
 - space/
	 - theme.css
	 - preview_large.png
	 - preview_small.png
 - cheese/
	 - theme.css
	 - preview_large.png
	 - preview_small.png
 - .....

It is suggested that the theme CSS file have a heading like this:

```css
/**
 * @id				default
 * @name			Default
 * @description		The default theme.
 * @author			Starbeamrainbowlabs
 * @author_link		https://starbeamrainbowlabs.com/
 * @minversion		v0.20
 */
```