3.7 KiB
In its simplest form, a theme is an empty folder with a config.json file containing {}
After that, every setting is optional, but you can override everything if you'd like to.
Overriding styles
If you want to tweak a few styles, you can create a
style.cssfile at the root of your documentation directory and it will be included automatically. By doing this, you don't need to create a new theme.
config.json options
Here is an example config.json file :
{
"favicon": "<theme_url>img/favicon.png",
"css": ["<theme_url>css/theme.min.css"],
"js": [],
"fonts": [
"https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700&subset=latin,cyrillic-ext,cyrillic"
],
"variants": {
"blue": {
"favicon": "<theme_url>img/favicon-blue.png",
"css": ["<theme_url>css/theme-blue.min.css"]
},
"green": {
"favicon": "<theme_url>img/favicon-green.png",
"css": ["<theme_url>css/theme-green.min.css"]
}
}
}
There are five options :
favicon: The URL to your faviconcss: An array of CSS Stylesheets to add to the pagejs: An array of JavaScript files to loadfonts: An array of Font sources, these are added as stylesheetsvariants: An object containing sub-themes. Each sub theme, can provide the same configurations as the main theme (favicon,css,js,fonts)
You will also notice this <theme_url> in the url.
This is automatically substituted with the final url to the theme when generating the final page.
There are two possible substitutions :
<theme_url>: The url to the current theme<base_url>: The url to the documentation root
Theme variants
Like the default Daux.io theme, you might want to provide variants of your theme.
In the example before, there were two variants : blue and green.
The configuration of a variant is added to the configuration of the main theme, it doesn't replace it.
For example the main CSS files defined are: ["<theme_url>css/theme.min.css"] and the green variant defines ["<theme_url>css/theme-green.min.css"].
The final list of CSS files will be ["<theme_url>css/theme.min.css", "<theme_url>css/theme-green.min.css"].
This doesn't apply to favicon, only the last value set is kept.
Setting the theme for your documentation
In your documentation's config.json (not the theme's config.json)
Change the theme option inside html
{
"themes_directory": "/home/user/themes",
"html": {
"theme": "{theme}-{variant}"
}
}
The name of the theme, is the folder name.
You can use the themes_directory setting if you want to specify a custom location of your themes folder.
A variant is optional, if you want to add one, separate it from the theme with a dash.
Overriding templates
By default, you have a list of templates in templates
You can create a folder named templates in your theme, copy-paste the original template in that folder, and you can modify it freely.
You can even do it one template at a time if you wish to do only small changes.
By default, we have the following templates :
content.php: The content page.home.php: The landing page.error.php: The page to show when a page is not found or some other error happened.partials/navbar_content.php: The content of the top navigation bar.partials/google_analytics.php: The script to load Google Analytics.partials/piwik_analytics.php: The script to load Piwik Analytics.layout/00_layout.php: The master template, containing the<html>tag.layout/05_page.php: The page layout, with left navigation.