daux.io/docs/10_For_Developers/Creating_a_Theme.md

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.

## `config.json` options

Here is an example `config.json` file :

```json
{
  "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 favicon
- __`css`__: An array of CSS Stylesheets to add to the page
- __`js`__: An array of JavaScript files to load
- __`fonts`__: An array of Font sources, these are added as stylesheets
- __`variants`__: 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`

```json
{
  "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.
Document custom themes, fixes #337 2016-01-07 22:13:49 +01:00			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.`

			## `config.json` options

			Here is an example `config.json` file :

			```json
			`{`
Clarify configuration options, put two spaces indents everywhere 2017-05-15 22:03:42 +02:00			`"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"]`
Document custom themes, fixes #337 2016-01-07 22:13:49 +01:00			`}`
Clarify configuration options, put two spaces indents everywhere 2017-05-15 22:03:42 +02:00			`}`
Document custom themes, fixes #337 2016-01-07 22:13:49 +01:00			`}`
			```

			`There are five options :`

			- __`favicon`__: The URL to your favicon
			- __`css`__: An array of CSS Stylesheets to add to the page
			- __`js`__: An array of JavaScript files to load
			- __`fonts`__: An array of Font sources, these are added as stylesheets
			- __`variants`__: 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`

			```json
			`{`
fixed incorrect documentation for themes location 2017-07-27 22:18:58 +02:00			`"themes_directory": "/home/user/themes",`
Clarify configuration options, put two spaces indents everywhere 2017-05-15 22:03:42 +02:00			`"html": {`
			`"theme": "{theme}-{variant}"`
			`}`
Document custom themes, fixes #337 2016-01-07 22:13:49 +01:00			`}`
			```

			`The name of the theme, is the folder name.`

fixed incorrect documentation for themes location 2017-07-27 22:18:58 +02:00			You can use the `themes_directory` setting if you want to specify a custom location of your `themes` folder.
Add a refrence to themes_path I had to check the source for this option 2016-07-28 10:22:22 +02:00
Document custom themes, fixes #337 2016-01-07 22:13:49 +01:00			`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.