diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 95fb7802..422e7c90 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -139,8 +139,11 @@ Lets you set a directory to a custom theme. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path. -See [styling your docs](styling-your-docs.md#custom-themes) for an explanation -of custom themes. +See [styling your docs](styling-your-docs.md#using-the-theme_dir) for details if +you would like to tweak an existing theme. + +See [custom themes](./custom-themes) if you would like to build your own theme +from the ground up. **default**: `null` diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index 9d4c2c78..c6ed7160 100644 --- a/docs/user-guide/custom-themes.md +++ b/docs/user-guide/custom-themes.md @@ -39,11 +39,19 @@ You would include the following setting to use the custom theme directory: theme_dir: 'custom_theme' -If used in combination with the `theme` configuration value a custom theme can -be used to replace only specific parts of a built-in theme. For example, with -the above layout and if you set `theme: mkdocs` then the `base.html` file -would replace that in the theme but otherwise it would remain the same. This -is useful if you want to make small adjustments to an existing theme. +!!! Note + + Generally, when building your own theme, the `theme` configurations setting + would be left blank. However, if used in combination with the `theme` + configuration value a custom theme can be used to replace only specific + parts of a built-in theme. For example, with the above layout and if you set + `theme: mkdocs` then the `base.html` file would replace that in the theme + but otherwise it would remain the same. This is useful if you want to make + small adjustments to an existing theme. + + For more specific information, see [styling your docs]. + +[styling your docs]: ./styling-your-docs.md#using-the-theme_dir ## Basic theme diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 9772ee6e..05406088 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/docs/user-guide/styling-your-docs.md @@ -4,21 +4,22 @@ How to style and theme your documentation. --- -MkDocs includes a number of different [built-in themes](#built-in-themes) and -[external themes](#bootstrap-and-bootswatch-themes) which can easily be -[customised with extra CSS or JavaScript](#customising-a-theme) or you can -create a [custom theme](/user-guide/custom-themes.md) for your documentation. +MkDocs includes a couple [built-in themes] as well as various [third party +themes], all of which can easily be customized with [extra CSS or +JavaScript][docs_dir] or overridden from the [theme directory][theme_dir]. You +can also create your own [custom theme] from the grown up for your +documentation. To use a theme that is included in MkDocs, simply add this to your `mkdocs.yml` config file. theme: readthedocs -Replace [`readthedocs`](#readthedocs) with any of the [built-in themes](#built- -in-themes) listed below. +Replace [`readthedocs`](#readthedocs) with any of the [built-in themes] listed below. -To create a new custom theme or more heavily customise an existing theme, see -the [custom themes](#custom-themes) section below. +To create a new custom theme see the [Custom Themes][custom theme] page, or to +more heavily customize an existing theme, see +the [Customizing a Theme][customize] section below. ## Built-in themes @@ -32,13 +33,21 @@ the [custom themes](#custom-themes) section below. ### Third Party Themes -Third party themes can be found in the MkDocs [community wiki]( -https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). +A list of third party themes can be found in the MkDocs [community wiki]. If you +have created your own, please feel free to add it to the list. -## Customising a Theme +## Customizing a Theme + +If you would like to make a few tweaks to an existing theme, there is no need to +create your own theme from scratch. For minor tweaks which only require some CSS +and/or JavaScript, you can use the [docs_dir]. However, for more complex +customizations, including overriding templates, you will need to use the +[theme_dir]. + +### Using the docs_dir The [extra_css] and [extra_javascript] configuration options can be used to -make tweaks and customisations to existing themes. To use these, you simply +make tweaks and customizations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your [documentation directory]. @@ -64,7 +73,98 @@ After making these changes, they should be visible when you run `mkdocs serve` - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated. +!!! note + + Any extra CSS or JavaScript files will be added to the generated HTML + document after the page content. If you desire to include a JavaScript + library, you may have better sucess including the library by using the + [theme_dir]. + +### Using the theme_dir + +The [theme_dir] configuration option can be used to point to a directory of +files which override the files in the theme set on the [theme] configuration +option. Any file in the `theme_dir` with the same name as a file in the `theme` +will replace the file of the same name in the `theme`. Any additional files in +the `theme_dir` will be added to the `theme`. The contents of the `theme_dir` +should mirror the directory structure of the `theme`. You may include templates, +JavaScript files, CSS files, images, fonts, or any other media included in a +theme. + +For example, the [mkdocs] theme ([browse source]), contains the following +directory structure (in part): + +```nohighlight +- css\ +- fonts\ +- img\ + - favicon.ico + - grid.png +- js\ +- 404.html +- base.html +- content.html +- nav-sub.html +- nav.html +- toc.html +``` + +To override any of the files contained in that theme, create a new directory +next to your `docs_dir`: + +```bash +mkdir custom_theme +``` + +And then point your `mkdocs.yml` configuration file at the new directory: + +```yaml +theme_dir: custom_theme +``` + +To override the 404 error page ("file not found"), add a new template file named +`404.html` to the `custom_theme` directory. For information on what can be +included in a template, review the documentation for building a [custom theme]. + +To override the favicon, you can add a new icon file at +`custom_theme/img/favicon.ico`. + +To include a JavaScript library, copy the library to the `custom_theme/js/` +directory. + +Your directory structure should now look like this: + +```nohighlight +- docs/ + - index.html +- custom_theme/ + - img/ + - favicon.ico + - js/ + - somelib.js + - 404.html +- config.yml +``` + +!!! Note + + Any files included in the `theme` but not included in the `theme_dir` will + still be utilized. The `theme_dir` will only override/replace files in the + `theme`. If you want to remove files, or build a theme from scratch, then + you should review the documentation for building a [custom theme]. + +[built-in themes]: #built-in-themes +[third party themes]: #third-party-themes +[docs_dir]: #using-the-docs_dir +[theme_dir]: #using-the-theme_dir +[customize]: #customizing-a-theme +[custom theme]: ./custom-themes.md [ReadTheDocs]: ./deploying-your-docs.md#readthedocs -[documentation directory]: /user-guide/configuration/#docs_dir -[extra_css]: /user-guide/configuration.md#extra_css -[extra_javascript]: /user-guide/configuration.md#extra_javascript +[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes +[documentation directory]: ./configuration/#docs_dir +[extra_css]: ./configuration.md#extra_css +[extra_javascript]: ./configuration.md#extra_javascript +[theme_dir]: ./configuration/#theme_dir +[theme]: ./configuration/#theme +[mkdocs]: #mkdocs +[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs