This guide will take you through creating your own CSS theme using Black Highlighter. You don't need to know any CSS if you just want to create a simple Black Highlighter theme.
How to set up your theme page
Picking a method
There are two ways of creating a theme page - the Include method and the Import method.
Here's a quick comparison of both.
| Include | Import |
|---|---|
| More difficult to set up | Easier to set up |
| Slightly easier for writers to add to their articles | Slightly harder for writers to add to their articles |
| Ability to provide usage instructions on the theme page | Ability to provide usage instructions on the theme page |
| Lets you see a list of pages that use the theme | Does not create a list |
| Lets you send both CSS and HTML to the themed page | Can only send CSS |
| Can style the translation box* | Cannot style the translation box |
*: Only if the proposed sidebar updates are implemented on the wiki.
We recommend the Include method for any and all themes. However, if you're sure that your theme will only ever be used by you, then the Import method is probably fine.
The Import method
Create a new page on any wiki - the Sandbox wiki is preferred. Create a code block, as follows:
[[code type="CSS"]]
[[/code]]
Inside this code block, write your CSS. If you're making a Black Highlighter theme, keep reading to find out what to write.
You can import this CSS onto any page by adding the following code to the page that wants to be themed (don't add it to your theme page):
[[module CSS]]
@import url(http://themedomain/local-code/themepage/1);
[[/module]]
Replace "themedomain" with the domain of the theme page - it's the first part of the URL. For example, "www.scp-wiki.net" or "scp-sandbox-3.wikidot.com".
Replace "themepage" with the full address of the theme page in the wiki. For example, "my-css-theme" or "component:theme". If the URL contains a colon, replace it with "%3A".1 For example, "component%3Atheme".
Tip! If you choose to write your CSS in Wikidot's text editor, keep in mind that you can press Ctrl+Y to insert a TAB character, for indenting your code.
The Include method
Create a new page on any wiki - the Sandbox wiki is preferred. Copy-paste the following code into it:
[[module CSS]]
@import url(http://themedomain/local-code/themepage/1);
[[/module]]
[[iftags +theme]]
Hello World!
Include this CSS on your page by adding the following code:
[[div class="code"]]
@@[[include :currentwiki:themepage]]@@
[[/div]]
[[code type="CSS"]]
[[/code]]
[[/iftags]]
Replace "themedomain" with the domain of the theme page - it's the first part of the URL. For example, "www.scp-wiki.net" or "scp-sandbox-3.wikidot.com".
After "themedomain", replace "themepage" with the full address of the theme page in the wiki. For example, "my-css-theme" or "component:theme". If the URL contains a colon, replace it with "%3A".2 For example, "component%3Atheme".
Replace "current-wiki" with the name of the wiki you're currently on. Usually it's either scp-wiki or scp-sandbox-3, but it can be sort of hard to find out when the admins of a site have changed the URL. For example the wiki name for http://kontainer.djkakt.us is kaktuskontainer, and for http://scp.avn.sh it's smlt. If in doubt, ask someone who knows.
After "current-wiki", replace the next "themepage" as described above, but this time do not replace any colons. For example: :scp-wiki:component:theme
Save the page. Then, at the bottom of the page, click "Tags", type "theme" into the box, then click Save.
There's a code block at the bottom of the page. Inside this code block, write your CSS. If you're making a Black Highlighter theme, keep reading to find out what to write.
How do you put your new theme on a page? You've already written the instructions yourself! Just copy the [[include]] onto a page and see if it works.
To see a list of all the pages that are using this theme, click +Options at the bottom of the page, then Backlinks. Wikidot will automatically generate a list for you.
Inside the [[iftags]] module, you can put literally anything you like (except more code blocks) and it won't show up on pages that use your theme. Add a usage guide with some examples of what your theme can do! Try here for inspiration.
How to make a Black Highlighter theme
If you're making a CSS theme for sigma9, you're going to need to learn some CSS yourself. If you're making a CSS theme for Black Highlighter, you're in luck!
BHL CSS is just a list of variables that you can change one-by-one without needing to write any real CSS yourself. The list of variables can be found here:
https://github.com/Nu-SCPTheme/Black-Highlighter/blob/master/src/css/root.css
The CSS you've not got is a list of variables. Everything starting with "--" is the name of a variable, and everything after the colon is that variable's value. These variables mostly control what colour things are, but there's some other things you can do as well. To make your theme all you need to do is change the value of some of those variables.
To do that, just copy the ones you want to change into your theme, inside a :root block. Only copy a variable if you're going to change it. If you're going to leave it the same, ignore it!
Make sure you change the first 3 variables right at the top!