mirror of
https://github.com/mkdocs/mkdocs.git
synced 2026-03-27 09:58:31 +07:00
Refactor docs (#2344)
The homepage has been redesigned. The "Installation" and "Getting Started" sections were moved to their own respective pages. Then, the homepage was restyled so that the list of features appear as a grid of cards. The developer specific pages were moved to a new section: `dev-guide`. Any old URLs redirect to the new ones.
This commit is contained in:
Waylan Limberg
@@ -12,5 +12,8 @@
|
||||
"MD007": { "indent": 4 },
|
||||
|
||||
// Exclude code block style
|
||||
"MD046": false
|
||||
"MD046": false,
|
||||
|
||||
// Allow inline HTML
|
||||
"MD033": false
|
||||
}
|
||||
|
||||
@@ -67,7 +67,7 @@ MkDocs can now benefit from recent bug fixes and new features, including the fol
|
||||
Plugin developers can now use the `on_build_error` hook
|
||||
to execute code when an exception is raised while building the site.
|
||||
|
||||
See [`on_build_error`](../user-guide/plugins.md#on_build_error)
|
||||
See [`on_build_error`](../dev-guide/plugins.md#on_build_error)
|
||||
in the Plugins documentation for details.
|
||||
|
||||
#### Two new exceptions: BuildError and PluginError (#2103)
|
||||
@@ -80,7 +80,7 @@ MkDocs now has two new exceptions defined in `mkdocs.exceptions`,
|
||||
* `BuildError` should not be used by third-party plugins developers
|
||||
and is reserved for internal use only.
|
||||
|
||||
See [`Handling errors`](../user-guide/plugins.md#handling-errors)
|
||||
See [`Handling errors`](../dev-guide/plugins.md#handling-errors)
|
||||
in the Plugins documentation for details.
|
||||
|
||||
#### Search Indexing Strategy configuration
|
||||
@@ -119,6 +119,7 @@ up horizontal space for better rendering of content like tables (#2193).
|
||||
property to accomodate this possible dynamic behavior. See #2305.
|
||||
* Updated highlight.js to 10.5.0. See #2313.
|
||||
* Bugfix: Search plugin now works with Japanese language. See #2178.
|
||||
* Documentation has been refactored (#1629).
|
||||
|
||||
## Version 1.1.2 (2020-05-14)
|
||||
|
||||
@@ -162,7 +163,7 @@ mirror the upstream configuration options. See the [theme
|
||||
documentation][rtd-docs] for details.
|
||||
|
||||
[upstream]: https://github.com/rtfd/sphinx_rtd_theme/
|
||||
[rtd-docs]: ../user-guide/styling-your-docs.md#readthedocs
|
||||
[rtd-docs]: ../user-guide/choosing-your-theme.md#readthedocs
|
||||
|
||||
#### Update `mkdocs` theme to Bootswatch 4.1.3 (#1563)
|
||||
|
||||
@@ -278,7 +279,7 @@ The changes included in the refactor are summarized below.
|
||||
files not in the `docs_dir`, exclude files, redefine page URLs (i.e.
|
||||
implement extensionless URLs), or to manipulate files in various other ways.
|
||||
|
||||
[on_files]: ../user-guide/plugins.md#on_files
|
||||
[on_files]: ../dev-guide/plugins.md#on_files
|
||||
|
||||
##### Backward Incompatible Changes
|
||||
|
||||
@@ -384,8 +385,8 @@ need to will be altered.
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
[base_url]: ../user-guide/custom-themes.md#base_url
|
||||
[url]: ../user-guide/custom-themes.md#url
|
||||
[base_url]: ../dev-guide/themes.md#base_url
|
||||
[url]: ../dev-guide/themes.md#url
|
||||
|
||||
#### Path Based Settings are Relative to Configuration File (#543)
|
||||
|
||||
@@ -453,7 +454,7 @@ Users can review the [configuration options][search config] available and theme
|
||||
authors should review how [search and themes] interact.
|
||||
|
||||
[search config]: ../user-guide/configuration.md#search
|
||||
[search and themes]: ../user-guide/custom-themes.md#search_and_themes
|
||||
[search and themes]: ../dev-guide/themes.md#search_and_themes
|
||||
|
||||
#### `theme_dir` Configuration Option fully Deprecated
|
||||
|
||||
@@ -537,7 +538,7 @@ then the `search` plugin will be included by default. See the
|
||||
[configuration][plugin_config] documentation for information on overriding the
|
||||
default.
|
||||
|
||||
[Plugin API]: ../user-guide/plugins.md
|
||||
[Plugin API]: ../dev-guide/plugins.md
|
||||
[plugin_config]: ../user-guide/configuration.md#plugins
|
||||
|
||||
#### Theme Customization. (#1164)
|
||||
@@ -574,7 +575,7 @@ theme:
|
||||
|
||||
See the [theme] configuration option documentation for details.
|
||||
|
||||
[Theme Configuration]: ../user-guide/custom-themes.md#theme-configuration
|
||||
[Theme Configuration]: ../dev-guide/themes.md#theme-configuration
|
||||
[theme]: ../user-guide/configuration.md#theme
|
||||
[custom_dir]: ../user-guide/configuration.md#custom_dir
|
||||
|
||||
@@ -592,7 +593,7 @@ template exists.
|
||||
##### Context Variables
|
||||
|
||||
Page specific variable names in the template context have been refactored as
|
||||
defined in [Custom Themes](../user-guide/custom-themes.md#page). The
|
||||
defined in [Custom Themes](../dev-guide/themes.md#page). The
|
||||
old variable names issued a warning in version 0.16, but have been removed in
|
||||
version 1.0.
|
||||
|
||||
@@ -610,14 +611,14 @@ user created and third-party templates:
|
||||
| previous_page | [page.previous_page]|
|
||||
| next_page | [page.next_page] |
|
||||
|
||||
[page]: ../user-guide/custom-themes.md#page
|
||||
[page.title]: ../user-guide/custom-themes.md#pagetitle
|
||||
[page.content]: ../user-guide/custom-themes.md#pagecontent
|
||||
[page.toc]: ../user-guide/custom-themes.md#pagetoc
|
||||
[page.meta]: ../user-guide/custom-themes.md#pagemeta
|
||||
[page.canonical_url]: ../user-guide/custom-themes.md#pagecanonical_url
|
||||
[page.previous_page]: ../user-guide/custom-themes.md#pageprevious_page
|
||||
[page.next_page]: ../user-guide/custom-themes.md#pagenext_page
|
||||
[page]: ../dev-guide/themes.md#page
|
||||
[page.title]: ../dev-guide/themes.md#pagetitle
|
||||
[page.content]: ../dev-guide/themes.md#pagecontent
|
||||
[page.toc]: ../dev-guide/themes.md#pagetoc
|
||||
[page.meta]: ../dev-guide/themes.md#pagemeta
|
||||
[page.canonical_url]: ../dev-guide/themes.md#pagecanonical_url
|
||||
[page.previous_page]: ../dev-guide/themes.md#pageprevious_page
|
||||
[page.next_page]: ../dev-guide/themes.md#pagenext_page
|
||||
|
||||
Additionally, a number of global variables have been altered and/or removed
|
||||
and user created and third-party templates should be updated as outlined below:
|
||||
@@ -697,7 +698,7 @@ the `extra_css` or `extra_javascript` config settings going forward.
|
||||
##### Page Context
|
||||
|
||||
Page specific variable names in the template context have been refactored as
|
||||
defined in [Custom Themes](../user-guide/custom-themes.md#page). The
|
||||
defined in [Custom Themes](../dev-guide/themes.md#page). The
|
||||
old variable names will issue a warning but continue to work for version 0.16,
|
||||
but may be removed in a future version.
|
||||
|
||||
@@ -715,14 +716,14 @@ user created and third-party templates:
|
||||
| previous_page | [page.previous_page]|
|
||||
| next_page | [page.next_page] |
|
||||
|
||||
[page]: ../user-guide/custom-themes.md#page
|
||||
[page.title]: ../user-guide/custom-themes.md#pagetitle
|
||||
[page.content]: ../user-guide/custom-themes.md#pagecontent
|
||||
[page.toc]: ../user-guide/custom-themes.md#pagetoc
|
||||
[page.meta]: ../user-guide/custom-themes.md#pagemeta
|
||||
[page.canonical_url]: ../user-guide/custom-themes.md#pagecanonical_url
|
||||
[page.previous_page]: ../user-guide/custom-themes.md#pageprevious_page
|
||||
[page.next_page]: ../user-guide/custom-themes.md#pagenext_page
|
||||
[page]: ../dev-guide/themes.md#page
|
||||
[page.title]: ../dev-guide/themes.md#pagetitle
|
||||
[page.content]: ../dev-guide/themes.md#pagecontent
|
||||
[page.toc]: ../dev-guide/themes.md#pagetoc
|
||||
[page.meta]: ../dev-guide/themes.md#pagemeta
|
||||
[page.canonical_url]: ../dev-guide/themes.md#pagecanonical_url
|
||||
[page.previous_page]: ../dev-guide/themes.md#pageprevious_page
|
||||
[page.next_page]: ../dev-guide/themes.md#pagenext_page
|
||||
|
||||
##### Global Context
|
||||
|
||||
@@ -811,7 +812,7 @@ overriding blocks in the same manner as the built-in themes. Third party themes
|
||||
are encouraged to wrap the various pieces of their templates in blocks in order
|
||||
to support such customization.
|
||||
|
||||
[blocks]: ../user-guide/styling-your-docs.md#overriding-template-blocks
|
||||
[blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks
|
||||
|
||||
#### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986)
|
||||
|
||||
@@ -929,12 +930,12 @@ They will be included with MkDocs by default until a future release. After that
|
||||
they will be installable with pip: `pip install mkdocs-bootstrap` and `pip
|
||||
install mkdocs-bootswatch`
|
||||
|
||||
See the documentation for [Styling your docs] for more information about using
|
||||
See the documentation for [Customizing Your Theme] for more information about using
|
||||
and customizing themes and [Custom themes] for creating and distributing new
|
||||
themes
|
||||
|
||||
[Styling your docs]: ../user-guide/styling-your-docs.md
|
||||
[Custom themes]: ../user-guide/custom-themes.md
|
||||
[Customizing Your Theme]: ../user-guide/customizing-your-theme.md
|
||||
[Custom themes]: ../dev-guide/themes.md
|
||||
|
||||
### Other Changes and Additions to Version 0.15.0
|
||||
|
||||
@@ -957,7 +958,7 @@ themes
|
||||
|
||||
[site_description]: ../user-guide/configuration.md#site_description
|
||||
[site_author]: ../user-guide/configuration.md#site_author
|
||||
[ReadTheDocs]: ../user-guide/styling-your-docs.md#readthedocs
|
||||
[ReadTheDocs]: ../user-guide/choosing-your-theme.md#readthedocs
|
||||
|
||||
## Version 0.14.0 (2015-06-09)
|
||||
|
||||
@@ -1042,7 +1043,7 @@ JavaScript library [lunr.js]. It has been added to both the `mkdocs` and
|
||||
for adding it to your own themes.
|
||||
|
||||
[lunr.js]: https://lunrjs.com/
|
||||
[supporting search]: ../user-guide/styling-your-docs.md#search-and-themes
|
||||
[supporting search]: ../dev-guide/themes.md#search-and-themes
|
||||
|
||||
#### New Command Line Interface
|
||||
|
||||
@@ -1073,7 +1074,7 @@ documentation.
|
||||
[extra_javascript]: ../user-guide/configuration.md#extra_javascript
|
||||
[extra_css]: ../user-guide/configuration.md#extra_css
|
||||
[extra_templates]: ../user-guide/configuration.md#extra_templates
|
||||
[global variables]: ../user-guide/styling-your-docs.md#global-context
|
||||
[global variables]: ../dev-guide/themes.md#global-context
|
||||
|
||||
### Other Changes and Additions to Version 0.13.0
|
||||
|
||||
|
||||
@@ -25,3 +25,25 @@ code.no-highlight {
|
||||
dd {
|
||||
padding-left: 20px;
|
||||
}
|
||||
|
||||
/* Homepage */
|
||||
|
||||
body.homepage div.jumbotron {
|
||||
margin-top: 1.5rem;
|
||||
padding-top: 1rem;
|
||||
padding-bottom: 0;
|
||||
}
|
||||
|
||||
body.homepage div.jumbotron div.card {
|
||||
margin-bottom: 2rem;
|
||||
}
|
||||
|
||||
body.homepage>div.container>div.row>div.col-md-3 {
|
||||
display: none;
|
||||
}
|
||||
|
||||
body.homepage>div.container>div.row>div.col-md-9 {
|
||||
margin-left: 0;
|
||||
flex: 0 0 100%;
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
16
docs/dev-guide/index.md
Normal file
16
docs/dev-guide/index.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Developer Guide
|
||||
|
||||
Extending MkDocs
|
||||
|
||||
---
|
||||
|
||||
The MkDocs Developer Guide provides documentation for developers of third
|
||||
party themes and plugins. Please see the [Contributing Guide] for information
|
||||
on contributing to MkDocs itself. You can jump directly to a page listed
|
||||
below, or use the *next* and *previous* buttons in the navigation bar at the
|
||||
top of the page to move through the documention in order.
|
||||
|
||||
- [Themes](themes.md)
|
||||
- [Plugins](plugins.md)
|
||||
|
||||
[Contributing Guide]: ../about/contributing.md
|
||||
@@ -472,16 +472,16 @@ Note that registering a plugin does not activate it. The user still needs to
|
||||
tell MkDocs to use it via the config.
|
||||
|
||||
[BasePlugin]:#baseplugin
|
||||
[config]: configuration.md#plugins
|
||||
[config]: ../user-guide/configuration.md#plugins
|
||||
[entry point]: #entry-point
|
||||
[env]: #on_env
|
||||
[events]: #events
|
||||
[extra_templates]: configuration.md#extra_templates
|
||||
[extra_templates]: ../user-guide/configuration.md#extra_templates
|
||||
[Global Events]: #global-events
|
||||
[Page Events]: #page-events
|
||||
[post_build]: #on_post_build
|
||||
[post_template]: #on_post_template
|
||||
[static_templates]: configuration.md#static_templates
|
||||
[static_templates]: ../user-guide/configuration.md#static_templates
|
||||
[Template Events]: #template-events
|
||||
[MkDocs Plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
|
||||
[on_build_error]: #on_build_error
|
||||
@@ -1,4 +1,4 @@
|
||||
# Custom themes
|
||||
# Developing Themes
|
||||
|
||||
A guide to creating and distributing custom themes.
|
||||
|
||||
@@ -6,24 +6,27 @@ A guide to creating and distributing custom themes.
|
||||
|
||||
!!! Note
|
||||
|
||||
If you are looking for third party themes, they are listed in the MkDocs
|
||||
[community wiki](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). If
|
||||
you want to share a theme you create, you should list it on the Wiki.
|
||||
If you are looking for existing third party themes, they are listed in the
|
||||
MkDocs [community wiki]. If you want to share a theme you create, you
|
||||
should list it on the Wiki.
|
||||
|
||||
When creating a new theme, you can either follow the steps in this guide to
|
||||
create one from scratch or you can download the `mkdocs-basic-theme` as a
|
||||
basic, yet complete, theme with all the boilerplate required. **You can find
|
||||
this base theme on [GitHub](https://github.com/mkdocs/mkdocs-basic-theme)**.
|
||||
It contains detailed comments in the code to describe the different features
|
||||
and their usage.
|
||||
this base theme on [GitHub][basic theme]**. It contains detailed comments in
|
||||
the code to describe the different features and their usage.
|
||||
|
||||
[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
|
||||
[basic theme]: https://github.com/mkdocs/mkdocs-basic-theme
|
||||
|
||||
## Creating a custom theme
|
||||
|
||||
The bare minimum required for a custom theme is a `main.html` [Jinja2 template]
|
||||
file which is placed in a directory that is *not* a child of the [docs_dir].
|
||||
Within `mkdocs.yml`, set the theme.[custom_dir] option to the path of the
|
||||
directory containing `main.html`. The path should be relative to the
|
||||
configuration file. For example, given this example project layout:
|
||||
The bare minimum required for a custom theme is a `main.html` [Jinja2
|
||||
template] file which is placed in a directory that is *not* a child of the
|
||||
[docs_dir]. Within `mkdocs.yml`, set the [`theme.custom_dir`][custom_dir]
|
||||
option to the path of the directory containing `main.html`. The path should be
|
||||
relative to the configuration file. For example, given this example project
|
||||
layout:
|
||||
|
||||
```no-highlight
|
||||
mkdocs.yml
|
||||
@@ -56,7 +59,7 @@ theme:
|
||||
`mkdocs` theme would remain unchanged. This is useful if you want to make
|
||||
small adjustments to an existing theme.
|
||||
|
||||
For more specific information, see [styling your docs].
|
||||
For more specific information, see [Customizing Your Theme].
|
||||
|
||||
!!! Warning
|
||||
|
||||
@@ -69,13 +72,13 @@ theme:
|
||||
the `theme.name` configuration option, then a `mkdocs_theme.yml` file
|
||||
is required for the theme.
|
||||
|
||||
[styling your docs]: ./styling-your-docs.md#using-the-theme-custom_dir
|
||||
[custom_dir]: ./configuration.md#custom_dir
|
||||
[name]: ./configuration.md#name
|
||||
[docs_dir]:./configuration.md#docs_dir
|
||||
[Customizing Your Theme]: ../user-guide/customizing-your-theme.md#using-the-theme-custom_dir
|
||||
[custom_dir]: ../user-guide/configuration.md#custom_dir
|
||||
[name]: ../user-guide/configuration.md#name
|
||||
[docs_dir]: ../user-guide/configuration.md#docs_dir
|
||||
[configuration]: #theme-configuration
|
||||
[packaged]: #packaging-themes
|
||||
[theme]: ./configuration.md#theme
|
||||
[theme]: ../user-guide/configuration.md#theme
|
||||
|
||||
## Basic theme
|
||||
|
||||
@@ -114,8 +117,8 @@ with one of the [built-in themes] and modify it accordingly.
|
||||
|
||||
[Jinja]: http://jinja.pocoo.org/
|
||||
[template inheritance]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
|
||||
[theme_dir]: ./styling-your-docs.md#using-the-theme_dir
|
||||
[blocks]: ./styling-your-docs.md#overriding-template-blocks
|
||||
[theme_dir]: ../user-guide/customizing-your-theme.md#using-the-theme_dir
|
||||
[blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks
|
||||
|
||||
## Theme Files
|
||||
|
||||
@@ -177,16 +180,16 @@ The `config` variable is an instance of MkDocs' config object generated from the
|
||||
`mkdocs.yml` config file. While you can use any config option, some commonly
|
||||
used options include:
|
||||
|
||||
* [config.site_name](./configuration.md#site_name)
|
||||
* [config.site_url](./configuration.md#site_url)
|
||||
* [config.site_author](./configuration.md#site_author)
|
||||
* [config.site_description](./configuration.md#site_description)
|
||||
* [config.extra_javascript](./configuration.md#extra_javascript)
|
||||
* [config.extra_css](./configuration.md#extra_css)
|
||||
* [config.repo_url](./configuration.md#repo_url)
|
||||
* [config.repo_name](./configuration.md#repo_name)
|
||||
* [config.copyright](./configuration.md#copyright)
|
||||
* [config.google_analytics](./configuration.md#google_analytics)
|
||||
* [config.site_name](../user-guide/configuration.md#site_name)
|
||||
* [config.site_url](../user-guide/configuration.md#site_url)
|
||||
* [config.site_author](../user-guide/configuration.md#site_author)
|
||||
* [config.site_description](../user-guide/configuration.md#site_description)
|
||||
* [config.extra_javascript](../user-guide/configuration.md#extra_javascript)
|
||||
* [config.extra_css](../user-guide/configuration.md#extra_css)
|
||||
* [config.repo_url](../user-guide/configuration.md#repo_url)
|
||||
* [config.repo_name](../user-guide/configuration.md#repo_name)
|
||||
* [config.copyright](../user-guide/configuration.md#copyright)
|
||||
* [config.google_analytics](../user-guide/configuration.md#google_analytics)
|
||||
|
||||
#### nav
|
||||
|
||||
@@ -194,7 +197,7 @@ The `nav` variable is used to create the navigation for the documentation. The
|
||||
`nav` object is an iterable of [navigation objects](#navigation-objects) as
|
||||
defined by the [nav] configuration setting.
|
||||
|
||||
[nav]: configuration.md#nav
|
||||
[nav]: ../user-guide/configuration.md#nav
|
||||
|
||||
In addition to the iterable of [navigation objects](#navigation-objects), the
|
||||
`nav` object contains the following attributes:
|
||||
@@ -357,7 +360,7 @@ For example, if `site_url: https://example.com/`, then the value of
|
||||
`site_url: https://example.com/bar/`, then the value of `page.abs_url` for the
|
||||
page `foo.md` would be `/bar/foo/`.
|
||||
|
||||
[site_url]: ./configuration.md#site_url
|
||||
[site_url]: ../user-guide/configuration.md#site_url
|
||||
|
||||
##### page.canonical_url
|
||||
|
||||
@@ -526,7 +529,7 @@ link objects.
|
||||
### Extra Context
|
||||
|
||||
Additional variables can be passed to the template with the
|
||||
[`extra`](./configuration.md#extra) configuration option. This is a
|
||||
[`extra`](../user-guide/configuration.md#extra) configuration option. This is a
|
||||
set of key value pairs that can make custom templates far more flexible.
|
||||
|
||||
For example, this could be used to include the project version of all pages
|
||||
@@ -692,8 +695,8 @@ index when it is available. The `index` object was new in MkDocs version *1.0*.
|
||||
[built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes
|
||||
[theme's configuration file]: #theme-configuration
|
||||
[lunr.js]: https://lunrjs.com/
|
||||
[site_dir]: configuration.md#site_dir
|
||||
[prebuild_index]: configuration.md#prebuild_index
|
||||
[site_dir]: ../user-guide/configuration.md#site_dir
|
||||
[prebuild_index]: ../user-guide/configuration.md#prebuild_index
|
||||
|
||||
## Packaging Themes
|
||||
|
||||
@@ -866,4 +869,4 @@ For a much more detailed guide, see the official Python packaging
|
||||
documentation for [Packaging and Distributing Projects].
|
||||
|
||||
[Packaging and Distributing Projects]: https://packaging.python.org/en/latest/distributing/
|
||||
[theme]: ./configuration.md#theme
|
||||
[theme]: ../user-guide/configuration.md#theme
|
||||
209
docs/getting-started.md
Normal file
209
docs/getting-started.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Getting Started with MkDocs
|
||||
|
||||
An introductory tutorial!
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
To install MkDocs, run the following command from the command line:
|
||||
|
||||
```bash
|
||||
pip install mkdocs
|
||||
```
|
||||
|
||||
For more details, see the [Installation Guide].
|
||||
|
||||
## Creating a new project
|
||||
|
||||
Getting started is super easy. To create a new project, run the following
|
||||
command from the command line:
|
||||
|
||||
```bash
|
||||
mkdocs new my-project
|
||||
cd my-project
|
||||
```
|
||||
|
||||
Take a moment to review the initial project that has been created for you.
|
||||
|
||||
|
||||
|
||||
There's a single configuration file named `mkdocs.yml`, and a folder named
|
||||
`docs` that will contain your documentation source files (`docs` is
|
||||
the default value for the [docs_dir] configuration setting). Right now the `docs`
|
||||
folder just contains a single documentation page, named `index.md`.
|
||||
|
||||
MkDocs comes with a built-in dev-server that lets you preview your documentation
|
||||
as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
|
||||
configuration file, and then start the server by running the `mkdocs serve`
|
||||
command:
|
||||
|
||||
```bash
|
||||
$ mkdocs serve
|
||||
INFO - Building documentation...
|
||||
INFO - Cleaning site directory
|
||||
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
|
||||
[I 160402 15:50:43 handlers:58] Start watching changes
|
||||
[I 160402 15:50:43 handlers:60] Start detecting changes
|
||||
```
|
||||
|
||||
Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
|
||||
home page being displayed:
|
||||
|
||||
|
||||
|
||||
The dev-server also supports auto-reloading, and will rebuild your documentation
|
||||
whenever anything in the configuration file, documentation directory, or theme
|
||||
directory changes.
|
||||
|
||||
Open the `docs/index.md` document in your text editor of choice, change the
|
||||
initial heading to `MkLorum`, and save your changes. Your browser will
|
||||
auto-reload and you should see your updated documentation immediately.
|
||||
|
||||
Now try editing the configuration file: `mkdocs.yml`. Change the
|
||||
[`site_name`][site_name] setting to `MkLorum` and save the file.
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
```
|
||||
|
||||
Your browser should immediately reload, and you'll see your new site name take
|
||||
effect.
|
||||
|
||||
|
||||
|
||||
## Adding pages
|
||||
|
||||
Now add a second page to your documentation:
|
||||
|
||||
```bash
|
||||
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
|
||||
```
|
||||
|
||||
As our documentation site will include some navigation headers, you may want to
|
||||
edit the configuration file and add some information about the order, title, and
|
||||
nesting of each page in the navigation header by adding a [`nav`][nav]
|
||||
setting:
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
```
|
||||
|
||||
Save your changes and you'll now see a navigation bar with `Home` and `About`
|
||||
items on the left as well as `Search`, `Previous`, and `Next` items on the
|
||||
right.
|
||||
|
||||
|
||||
|
||||
Try the menu items and navigate back and forth between pages. Then click on
|
||||
`Search`. A search dialog will appear, allowing you to search for any text on
|
||||
any page. Notice that the search results include every occurrence of the search
|
||||
term on the site and links directly to the section of the page in which the
|
||||
search term appears. You get all of that with no effort or configuration on your
|
||||
part!
|
||||
|
||||
|
||||
|
||||
## Theming our documentation
|
||||
|
||||
Now change the configuration file to alter how the documentation is displayed by
|
||||
changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
theme: readthedocs
|
||||
```
|
||||
|
||||
Save your changes, and you'll see the ReadTheDocs theme being used.
|
||||
|
||||
|
||||
|
||||
## Changing the Favicon Icon
|
||||
|
||||
By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
|
||||
an `img` subdirectory in the `docs` directory and copy your custom `favicon.ico`
|
||||
file to that directory. MkDocs will automatically detect and use that file as your
|
||||
favicon icon.
|
||||
|
||||
[MkDocs favicon]: img/favicon.ico
|
||||
|
||||
## Building the site
|
||||
|
||||
That's looking good. You're ready to deploy the first pass of your `MkLorum`
|
||||
documentation. First build the documentation:
|
||||
|
||||
```bash
|
||||
mkdocs build
|
||||
```
|
||||
|
||||
This will create a new directory, named `site`. Take a look inside the
|
||||
directory:
|
||||
|
||||
```bash
|
||||
$ ls site
|
||||
about fonts index.html license search.html
|
||||
css img js mkdocs sitemap.xml
|
||||
```
|
||||
|
||||
Notice that your source documentation has been output as two HTML files named
|
||||
`index.html` and `about/index.html`. You also have various other media that's
|
||||
been copied into the `site` directory as part of the documentation theme. You
|
||||
even have a `sitemap.xml` file and `mkdocs/search_index.json`.
|
||||
|
||||
If you're using source code control such as `git` you probably don't want to
|
||||
check your documentation builds into the repository. Add a line containing
|
||||
`site/` to your `.gitignore` file.
|
||||
|
||||
```bash
|
||||
echo "site/" >> .gitignore
|
||||
```
|
||||
|
||||
If you're using another source code control tool you'll want to check its
|
||||
documentation on how to ignore specific directories.
|
||||
|
||||
## Other Commands and Options
|
||||
|
||||
There are various other commands and options available. For a complete list of
|
||||
commands, use the `--help` flag:
|
||||
|
||||
```bash
|
||||
mkdocs --help
|
||||
```
|
||||
|
||||
To view a list of options available on a given command, use the `--help` flag
|
||||
with that command. For example, to get a list of all options available for the
|
||||
`build` command run the following:
|
||||
|
||||
```bash
|
||||
mkdocs build --help
|
||||
```
|
||||
|
||||
## Deploying
|
||||
|
||||
The documentation site that you just built only uses static files so you'll be
|
||||
able to host it from pretty much anywhere. Simply upload the contents of the
|
||||
entire `site` directory to wherever you're hosting your website from and
|
||||
you're done. For specific instructions on a number of common hosts, see the
|
||||
[Deploying your Docs][deploy] page.
|
||||
|
||||
## Getting help
|
||||
|
||||
See the [User Guide] for more complete documentation of all of MkDocs' features.
|
||||
|
||||
To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues].
|
||||
|
||||
[Installation Guide]: user-guide/installation.md
|
||||
[docs_dir]: user-guide/configuration.md#docs_dir
|
||||
[deploy]: user-guide/deploying-your-docs.md
|
||||
[nav]: user-guide/configuration.md#nav
|
||||
[GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions
|
||||
[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
|
||||
[site_name]: user-guide/configuration.md#site_name
|
||||
[theme]: user-guide/configuration.md#theme
|
||||
[User Guide]: user-guide/index.md
|
||||
434
docs/index.md
434
docs/index.md
@@ -4,360 +4,86 @@ Project documentation with Markdown.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MkDocs is a **fast**, **simple** and **downright gorgeous** static site
|
||||
generator that's geared towards building project documentation. Documentation
|
||||
source files are written in Markdown, and configured with a single YAML
|
||||
configuration file. Start by reading the introduction below, then check the User
|
||||
Guide for more info.
|
||||
|
||||
### Host anywhere
|
||||
|
||||
MkDocs builds completely static HTML sites that you can host on GitHub pages,
|
||||
Amazon S3, or [anywhere][deploy] else you choose.
|
||||
|
||||
### Great themes available
|
||||
|
||||
There's a stack of good looking [themes] available for MkDocs. Choose between
|
||||
the built in themes: [mkdocs] and [readthedocs], select one of the 3rd
|
||||
party themes listed on the [MkDocs Themes] wiki page, or [build your own].
|
||||
|
||||
### Preview your site as you work
|
||||
|
||||
The built-in dev-server allows you to preview your documentation as you're
|
||||
writing it. It will even auto-reload and refresh your browser whenever you save
|
||||
your changes.
|
||||
|
||||
### Easy to customize
|
||||
|
||||
Get your project documentation looking just the way you want it by customizing
|
||||
the [theme] and/or installing some [plugins].
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Install with a Package Manager
|
||||
|
||||
If you have and use a package manager (such as [apt-get], [dnf], [homebrew],
|
||||
[yum], [chocolatey], etc.) to install packages on your system, then you may
|
||||
want to search for a "MkDocs" package and, if a recent version is available,
|
||||
install it with your package manager (check your system's documentation for
|
||||
details). That's it, you're done! Skip down to [Getting Started](#getting-started).
|
||||
|
||||
If your package manager does not have a recent "MkDocs" package, you can still
|
||||
use your package manager to install "Python" and "pip". Then you can use pip to
|
||||
[install MkDocs](#installing-mkdocs).
|
||||
|
||||
[apt-get]: https://help.ubuntu.com/community/AptGet/Howto
|
||||
[homebrew]: https://brew.sh/
|
||||
[dnf]: https://dnf.readthedocs.io/en/latest/index.html
|
||||
[yum]: http://yum.baseurl.org/
|
||||
[chocolatey]: https://chocolatey.org/
|
||||
|
||||
### Manual Installation
|
||||
|
||||
In order to manually install MkDocs you'll need [Python] installed on your
|
||||
system, as well as the Python package manager, [pip]. You can check if you have
|
||||
these already installed from the command line:
|
||||
|
||||
```bash
|
||||
$ python --version
|
||||
Python 3.8.2
|
||||
$ pip --version
|
||||
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
|
||||
```
|
||||
|
||||
MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3.
|
||||
|
||||
#### Installing Python
|
||||
|
||||
Install [Python] by downloading an installer appropriate for your system from
|
||||
[python.org] and running it.
|
||||
|
||||
!!! Note
|
||||
|
||||
If you are installing Python on Windows, be sure to check the box to have
|
||||
Python added to your PATH if the installer offers such an option (it's
|
||||
normally off by default).
|
||||
|
||||
|
||||
|
||||
[python.org]: https://www.python.org/downloads/
|
||||
|
||||
#### Installing pip
|
||||
|
||||
If you're using a recent version of Python, the Python package manager, [pip],
|
||||
is most likely installed by default. However, you may need to upgrade pip to the
|
||||
lasted version:
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
```
|
||||
|
||||
If you need to install [pip] for the first time, download [get-pip.py].
|
||||
Then run the following command to install it:
|
||||
|
||||
```bash
|
||||
python get-pip.py
|
||||
```
|
||||
|
||||
#### Installing MkDocs
|
||||
|
||||
Install the `mkdocs` package using pip:
|
||||
|
||||
```bash
|
||||
pip install mkdocs
|
||||
```
|
||||
|
||||
You should now have the `mkdocs` command installed on your system. Run `mkdocs
|
||||
--version` to check that everything worked okay.
|
||||
|
||||
```bash
|
||||
$ mkdocs --version
|
||||
mkdocs, version 0.15.3
|
||||
```
|
||||
|
||||
!!! Note
|
||||
If you would like manpages installed for MkDocs, the [click-man] tool can
|
||||
generate and install them for you. Simply run the following two commands:
|
||||
|
||||
pip install click-man
|
||||
click-man --target path/to/man/pages mkdocs
|
||||
|
||||
See the [click-man documentation] for an explanation of why manpages are
|
||||
not automatically generated and installed by pip.
|
||||
|
||||
[click-man]: https://github.com/click-contrib/click-man
|
||||
[click-man documentation]: https://github.com/click-contrib/click-man#automatic-man-page-installation-with-setuptools-and-pip
|
||||
|
||||
!!! Note
|
||||
If you are using Windows, some of the above commands may not work
|
||||
out-of-the-box.
|
||||
|
||||
A quick solution may be to preface every Python command with `python -m`
|
||||
like this:
|
||||
|
||||
python -m pip install mkdocs
|
||||
python -m mkdocs
|
||||
|
||||
For a more permanent solution, you may need to edit your `PATH` environment
|
||||
variable to include the `Scripts` directory of your Python installation.
|
||||
Recent versions of Python include a script to do this for you. Navigate to
|
||||
your Python installation directory (for example `C:\Python38\`), open the
|
||||
`Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
|
||||
clicking on it. Alternatively, you can [download][a2p] the script and run it
|
||||
(`python win_add2path.py`).
|
||||
|
||||
[a2p]: https://svn.python.org/projects/python/trunk/Tools/scripts/win_add2path.py
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
Getting started is super easy.
|
||||
|
||||
```bash
|
||||
mkdocs new my-project
|
||||
cd my-project
|
||||
```
|
||||
|
||||
Take a moment to review the initial project that has been created for you.
|
||||
|
||||
|
||||
|
||||
There's a single configuration file named `mkdocs.yml`, and a folder named
|
||||
`docs` that will contain your documentation source files (`docs` is
|
||||
the default value for the [docs_dir] configuration setting). Right now the `docs`
|
||||
folder just contains a single documentation page, named `index.md`.
|
||||
|
||||
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
|
||||
|
||||
MkDocs comes with a built-in dev-server that lets you preview your documentation
|
||||
as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
|
||||
configuration file, and then start the server by running the `mkdocs serve`
|
||||
command:
|
||||
|
||||
```bash
|
||||
$ mkdocs serve
|
||||
INFO - Building documentation...
|
||||
INFO - Cleaning site directory
|
||||
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
|
||||
[I 160402 15:50:43 handlers:58] Start watching changes
|
||||
[I 160402 15:50:43 handlers:60] Start detecting changes
|
||||
```
|
||||
|
||||
Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
|
||||
home page being displayed:
|
||||
|
||||
|
||||
|
||||
The dev-server also supports auto-reloading, and will rebuild your documentation
|
||||
whenever anything in the configuration file, documentation directory, or theme
|
||||
directory changes.
|
||||
|
||||
Open the `docs/index.md` document in your text editor of choice, change the
|
||||
initial heading to `MkLorum`, and save your changes. Your browser will
|
||||
auto-reload and you should see your updated documentation immediately.
|
||||
|
||||
Now try editing the configuration file: `mkdocs.yml`. Change the
|
||||
[`site_name`][site_name] setting to `MkLorum` and save the file.
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
```
|
||||
|
||||
Your browser should immediately reload, and you'll see your new site name take
|
||||
effect.
|
||||
|
||||
|
||||
|
||||
## Adding pages
|
||||
|
||||
Now add a second page to your documentation:
|
||||
|
||||
```bash
|
||||
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
|
||||
```
|
||||
|
||||
As our documentation site will include some navigation headers, you may want to
|
||||
edit the configuration file and add some information about the order, title, and
|
||||
nesting of each page in the navigation header by adding a [`nav`][nav]
|
||||
setting:
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
```
|
||||
|
||||
Save your changes and you'll now see a navigation bar with `Home` and `About`
|
||||
items on the left as well as `Search`, `Previous`, and `Next` items on the
|
||||
right.
|
||||
|
||||
|
||||
|
||||
Try the menu items and navigate back and forth between pages. Then click on
|
||||
`Search`. A search dialog will appear, allowing you to search for any text on
|
||||
any page. Notice that the search results include every occurrence of the search
|
||||
term on the site and links directly to the section of the page in which the
|
||||
search term appears. You get all of that with no effort or configuration on your
|
||||
part!
|
||||
|
||||
|
||||
|
||||
## Theming our documentation
|
||||
|
||||
Now change the configuration file to alter how the documentation is displayed by
|
||||
changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
|
||||
|
||||
```yaml
|
||||
site_name: MkLorum
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
theme: readthedocs
|
||||
```
|
||||
|
||||
Save your changes, and you'll see the ReadTheDocs theme being used.
|
||||
|
||||
|
||||
|
||||
## Changing the Favicon Icon
|
||||
|
||||
By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
|
||||
an `img` subdirectory in the `docs` directory and copy your custom `favicon.ico`
|
||||
file to that directory. MkDocs will automatically detect and use that file as your
|
||||
favicon icon.
|
||||
|
||||
[MkDocs favicon]: /img/favicon.ico
|
||||
|
||||
## Building the site
|
||||
|
||||
That's looking good. You're ready to deploy the first pass of your `MkLorum`
|
||||
documentation. First build the documentation:
|
||||
|
||||
```bash
|
||||
mkdocs build
|
||||
```
|
||||
|
||||
This will create a new directory, named `site`. Take a look inside the
|
||||
directory:
|
||||
|
||||
```bash
|
||||
$ ls site
|
||||
about fonts index.html license search.html
|
||||
css img js mkdocs sitemap.xml
|
||||
```
|
||||
|
||||
Notice that your source documentation has been output as two HTML files named
|
||||
`index.html` and `about/index.html`. You also have various other media that's
|
||||
been copied into the `site` directory as part of the documentation theme. You
|
||||
even have a `sitemap.xml` file and `mkdocs/search_index.json`.
|
||||
|
||||
If you're using source code control such as `git` you probably don't want to
|
||||
check your documentation builds into the repository. Add a line containing
|
||||
`site/` to your `.gitignore` file.
|
||||
|
||||
```bash
|
||||
echo "site/" >> .gitignore
|
||||
```
|
||||
|
||||
If you're using another source code control tool you'll want to check its
|
||||
documentation on how to ignore specific directories.
|
||||
|
||||
After some time, files may be removed from the documentation but they will still
|
||||
reside in the `site` directory. To remove those stale files, just run `mkdocs`
|
||||
with the `--clean` switch.
|
||||
|
||||
```bash
|
||||
mkdocs build --clean
|
||||
```
|
||||
|
||||
## Other Commands and Options
|
||||
|
||||
There are various other commands and options available. For a complete list of
|
||||
commands, use the `--help` flag:
|
||||
|
||||
```bash
|
||||
mkdocs --help
|
||||
```
|
||||
|
||||
To view a list of options available on a given command, use the `--help` flag
|
||||
with that command. For example, to get a list of all options available for the
|
||||
`build` command run the following:
|
||||
|
||||
```bash
|
||||
mkdocs build --help
|
||||
```
|
||||
|
||||
## Deploying
|
||||
|
||||
The documentation site that you just built only uses static files so you'll be
|
||||
able to host it from pretty much anywhere. Simply upload the contents of the
|
||||
entire `site` directory to wherever you're hosting your website from and
|
||||
you're done. For specific instructions on a number of common hosts, see the
|
||||
[Deploying your Docs][deploy] page.
|
||||
|
||||
## Getting help
|
||||
|
||||
To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues].
|
||||
|
||||
[deploy]: user-guide/deploying-your-docs/
|
||||
[mkdocs]: user-guide/styling-your-docs/#mkdocs
|
||||
[readthedocs]: user-guide/styling-your-docs/#readthedocs
|
||||
[theme]: user-guide/styling-your-docs/
|
||||
[themes]: user-guide/styling-your-docs/
|
||||
[plugins]: user-guide/plugins/
|
||||
[MkDocs Themes]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
|
||||
[build your own]: user-guide/custom-themes/
|
||||
[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
|
||||
[nav]: user-guide/configuration/#nav
|
||||
[GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions
|
||||
[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
|
||||
[pip]: https://pip.readthedocs.io/en/stable/installing/
|
||||
[Python]: https://www.python.org/
|
||||
[site_name]: user-guide/configuration/#site_name
|
||||
[theme]: user-guide/configuration/#theme
|
||||
configuration file. Start by reading the [introductory tutorial], then check the
|
||||
[User Guide] for more information.
|
||||
|
||||
[introductory tutorial]: getting-started.md
|
||||
[User Guide]: user-guide/index.md
|
||||
|
||||
<div class="text-center">
|
||||
<a href="getting-started/" class="btn btn-primary" role="button">Getting Started</a>
|
||||
<a href="user-guide/" class="btn btn-primary" role="button">User Guide</a>
|
||||
</div>
|
||||
|
||||
<div class="jumbotron">
|
||||
<h2 class="display-4 text-center">Features</h2>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<div class="card">
|
||||
<div class="card-body">
|
||||
<h3 class="card-title">Great themes available</h3>
|
||||
<p class="card-text">
|
||||
There's a stack of good looking <a
|
||||
href="user-guide/choosing-your-theme">themes</a> available for
|
||||
MkDocs. Choose between the built in themes: <a
|
||||
href="user-guide/choosing-your-theme/#mkdocs">mkdocs</a> and <a
|
||||
href="user-guide/choosing-your-theme/#readthedocs">readthedocs</a>,
|
||||
select one of the third-party themes listed on the <a
|
||||
href="">MkDocs Themes</a> wiki page, or <a href="">build your
|
||||
own</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-sm-6">
|
||||
<div class="card">
|
||||
<div class="card-body">
|
||||
<h3 class="card-title">Easy to customize</h3>
|
||||
<p class="card-text">
|
||||
Get your project documentation looking just the way you want it by
|
||||
<a href="user-guide/customizing-your-theme/">customizing your
|
||||
theme</a> and/or installing some <a
|
||||
href="user-guide/configuration/#plugins">plugins</a>. Modify
|
||||
Markdown's behavior with <a
|
||||
href="user-guide/configuration/#markdown_extensions">Markdown
|
||||
extensions</a>. Many <a
|
||||
href="user-guide/configuration/">configuration options</a> are
|
||||
available.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="row">
|
||||
<div class="col-sm-6">
|
||||
<div class="card">
|
||||
<div class="card-body">
|
||||
<h3 class="card-title">Preview your site as you work</h3>
|
||||
<p class="card-text">
|
||||
The built-in dev-server allows you to preview your documentation
|
||||
as you're writing it. It will even auto-reload and refresh your
|
||||
browser whenever you save your changes.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-sm-6">
|
||||
<div class="card">
|
||||
<div class="card-body">
|
||||
<h3 class="card-title">Host anywhere</h3>
|
||||
<p class="card-text">
|
||||
MkDocs builds completely static HTML sites that you can host on
|
||||
GitHub pages, Amazon S3, or <a
|
||||
href="user-guide/deploying-your-docs/">anywhere</a> else you
|
||||
choose.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
136
docs/user-guide/choosing-your-theme.md
Normal file
136
docs/user-guide/choosing-your-theme.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Choosing your Theme
|
||||
|
||||
Selecting and configuring a theme.
|
||||
|
||||
---
|
||||
|
||||
MkDocs includes two built-in themes ([mkdocs](#mkdocs) and
|
||||
[readthedocs](#readthedocs)), as documented below. However, many [third party
|
||||
themes] are available to choose from as well.
|
||||
|
||||
To choose a theme, set the [theme] configuration option in your `mkdocs.yml`
|
||||
config file.
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
name: readthedocs
|
||||
```
|
||||
|
||||
## mkdocs
|
||||
|
||||
The default theme, which was built as a custom [Bootstrap] theme, supports most
|
||||
every feature of MkDocs.
|
||||
|
||||
|
||||
|
||||
In addition to the default [theme configuration options][theme], the `mkdocs` theme
|
||||
supports the following options:
|
||||
|
||||
* __`highlightjs`__: Enables highlighting of source code in code blocks using
|
||||
the [highlight.js] JavaScript library. Default: `True`.
|
||||
|
||||
* __`hljs_style`__: The highlight.js library provides 79 different [styles]
|
||||
(color variations) for highlighting source code in code blocks. Set this to
|
||||
the name of the desired style. Default: `github`.
|
||||
|
||||
* __`hljs_languages`__: By default, highlight.js only supports 23 common
|
||||
languages. List additional languages here to include support for them.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
highlightjs: true
|
||||
hljs_languages:
|
||||
- yaml
|
||||
- rust
|
||||
|
||||
* __`shortcuts`__: Defines keyboard shortcut keys.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
shortcuts:
|
||||
help: 191 # ?
|
||||
next: 78 # n
|
||||
previous: 80 # p
|
||||
search: 83 # s
|
||||
|
||||
All values must be numeric key codes. It is best to use keys which are
|
||||
available on all keyboards. You may use <https://keycode.info/> to determine
|
||||
the key code for a given key.
|
||||
|
||||
* __`help`__: Display a help modal which lists the keyboard shortcuts.
|
||||
Default: `191` (?)
|
||||
|
||||
* __`next`__: Navigate to the "next" page. Default: `78` (n)
|
||||
|
||||
* __`previous`__: Navigate to the "previous" page. Default: `80` (p)
|
||||
|
||||
* __`search`__: Display the search modal. Default: `83` (s)
|
||||
|
||||
* __`navigation_depth`__: The maximum depth of the navigation tree in the
|
||||
sidebar. Default: `2`.
|
||||
|
||||
* __`nav_style`__: This adjusts the visual style for the top navigation bar; by
|
||||
default, this is set to `primary` (the default), but it can also be set to
|
||||
`dark` or `light`.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
nav_style: dark
|
||||
|
||||
## readthedocs
|
||||
|
||||
A clone of the default theme used by the [Read the Docs] service, which offers
|
||||
the same restricted feature-set as its parent theme. Like its parent theme, only
|
||||
two levels of navigation are supported.
|
||||
|
||||
|
||||
|
||||
In addition to the default [theme configuration options][theme], the `readthedocs`
|
||||
theme supports the following options:
|
||||
|
||||
* __`highlightjs`__: Enables highlighting of source code in code blocks using
|
||||
the [highlight.js] JavaScript library. Default: `True`.
|
||||
|
||||
* __`hljs_languages`__: By default, highlight.js only supports 23 common
|
||||
languages. List additional languages here to include support for them.
|
||||
|
||||
theme:
|
||||
name: readthedocs
|
||||
highlightjs: true
|
||||
hljs_languages:
|
||||
- yaml
|
||||
- rust
|
||||
|
||||
* __`include_homepage_in_sidebar`__: Lists the homepage in the sidebar menu. As
|
||||
MkDocs requires that the homepage be listed in the `nav` configuration
|
||||
option, this setting allows the homepage to be included or excluded from
|
||||
the sidebar. Note that the site name/logo always links to the homepage.
|
||||
Default: `True`.
|
||||
|
||||
* __`prev_next_buttons_location`__: One of `bottom`, `top`, `both` , or `none`.
|
||||
Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`.
|
||||
|
||||
* __`navigation_depth`__: The maximum depth of the navigation tree in the
|
||||
sidebar. Default: `4`.
|
||||
|
||||
* __`collapse_navigation`__: Only include the page section headers in the
|
||||
sidebar for the current page. Default: `True`.
|
||||
|
||||
* __`titles_only`__: Only include page titles in the sidebar, excluding all
|
||||
section headers for all pages. Default: `False`.
|
||||
|
||||
* __`sticky_navigation`__: If True, causes the sidebar to scroll with the main
|
||||
page content as you scroll the page. Default: `True`.
|
||||
|
||||
## Third Party 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.
|
||||
|
||||
[third party themes]: #third-party-themes
|
||||
[theme]: configuration.md#theme
|
||||
[Bootstrap]: https://getbootstrap.com/
|
||||
[highlight.js]: https://highlightjs.org/
|
||||
[styles]: https://highlightjs.org/static/demo/
|
||||
[Read the Docs]: https://readthedocs.org/
|
||||
[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
|
||||
@@ -263,7 +263,7 @@ Sets the theme and theme specific configuration of your documentation site.
|
||||
May be either a string or a set of key/value pairs.
|
||||
|
||||
If a string, it must be the string name of a known installed theme. For a list
|
||||
of available themes visit [styling your docs].
|
||||
of available themes visit [Choosing Your Theme].
|
||||
|
||||
An example set of key/value pairs might look something like this:
|
||||
|
||||
@@ -283,7 +283,7 @@ If a set of key/value pairs, the following nested keys can be defined:
|
||||
#### name:
|
||||
|
||||
The string name of a known installed theme. For a list of available themes
|
||||
visit [styling your docs].
|
||||
visit [Choosing Your Theme].
|
||||
|
||||
#### custom_dir:
|
||||
|
||||
@@ -292,11 +292,11 @@ If a set of key/value pairs, the following nested keys can be defined:
|
||||
your configuration file or it can be an absolute directory path from the
|
||||
root of your local file system.
|
||||
|
||||
See [styling your docs][theme_dir] for details if you would like to tweak an
|
||||
See [Customizing Your Theme][theme_dir] for details if you would like to tweak an
|
||||
existing theme.
|
||||
|
||||
See [custom themes] if you would like to build your own theme from the
|
||||
ground up.
|
||||
See the [Theme Developer Guide] if you would like to build your own theme
|
||||
from the ground up.
|
||||
|
||||
#### static_templates:
|
||||
|
||||
@@ -650,18 +650,18 @@ plugins:
|
||||
|
||||
**default**: `full`
|
||||
|
||||
[custom themes]: custom-themes.md
|
||||
[variables that are available]: custom-themes.md#template-variables
|
||||
[Theme Developer Guide]: ../dev-guide/themes.md
|
||||
[variables that are available]: ../dev-guide/themes.md#template-variables
|
||||
[pymdk-extensions]: https://python-markdown.github.io/extensions/
|
||||
[pymkd]: https://python-markdown.github.io/
|
||||
[smarty]: https://python-markdown.github.io/extensions/smarty/
|
||||
[exts]: https://python-markdown.github.io/extensions/
|
||||
[3rd]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
|
||||
[configuring pages and navigation]: writing-your-docs.md#configure-pages-and-navigation
|
||||
[theme_dir]: styling-your-docs.md#using-the-theme_dir
|
||||
[styling your docs]: styling-your-docs.md
|
||||
[theme_dir]: customizing-your-theme.md#using-the-theme_dir
|
||||
[choosing your theme]: choosing-your-theme.md
|
||||
[extra_css]: #extra_css
|
||||
[Plugins]: plugins.md
|
||||
[Plugins]: ../dev-guide/plugins.md
|
||||
[lunr.js]: https://lunrjs.com/
|
||||
[ISO 639-1]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
|
||||
[Lunr Languages]: https://github.com/MihaiValentin/lunr-languages#lunr-languages-----
|
||||
|
||||
231
docs/user-guide/customizing-your-theme.md
Normal file
231
docs/user-guide/customizing-your-theme.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Customizing Your Theme
|
||||
|
||||
Altering a theme to suit your needs.
|
||||
|
||||
---
|
||||
|
||||
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](#using-the-docs_dir).
|
||||
However, for more complex customizations, including overriding templates, you
|
||||
will need to [use the theme custom_dir](#using-the-theme-custom_dir) setting.
|
||||
|
||||
## Using the docs_dir
|
||||
|
||||
The [extra_css] and [extra_javascript] configuration options can be used to
|
||||
make tweaks and customizations to existing themes. To use these, you simply
|
||||
need to include either CSS or JavaScript files within your [documentation
|
||||
directory].
|
||||
|
||||
For example, to change the colour of the headers in your documentation, create
|
||||
a file called `extra.css` and place it next to the documentation Markdown. In
|
||||
that file add the following CSS.
|
||||
|
||||
```CSS
|
||||
h1 {
|
||||
color: red;
|
||||
}
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
||||
If you are deploying your documentation with [ReadTheDocs]. You will need
|
||||
to explicitly list the CSS and JavaScript files you want to include in
|
||||
your config. To do this, add the following to your mkdocs.yml.
|
||||
|
||||
extra_css: [extra.css]
|
||||
|
||||
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 success including the library by using the
|
||||
theme [custom_dir].
|
||||
|
||||
## Using the theme custom_dir
|
||||
|
||||
The [`theme.custom_dir`][custom_dir] configuration option can be used to point
|
||||
to a directory of files which override the files in a parent theme. The parent
|
||||
theme would be the theme defined in the [`theme.name`][name] configuration
|
||||
option. Any file in the `custom_dir` with the same name as a file in the
|
||||
parent theme will replace the file of the same name in the parent theme. Any
|
||||
additional files in the `custom_dir` will be added to the parent theme. The
|
||||
contents of the `custom_dir` should mirror the directory structure of the
|
||||
parent theme. You may include templates, JavaScript files, CSS files, images,
|
||||
fonts, or any other media included in a theme.
|
||||
|
||||
!!! Note
|
||||
|
||||
For this to work, the `theme.name` setting must be set to a known
|
||||
installed theme. If the `name` setting is instead set to `null` (or not
|
||||
defined), then there is no theme to override and the contents of the
|
||||
`custom_dir` must be a complete, standalone theme. See the [Theme
|
||||
Developer Guide][custom theme] for more information.
|
||||
|
||||
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:
|
||||
name: mkdocs
|
||||
custom_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 [Theme Developer Guide][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 parent theme (defined in `name`) but not
|
||||
included in the `custom_dir` will still be utilized. The `custom_dir` will
|
||||
only override/replace files in the parent theme. If you want to remove
|
||||
files, or build a theme from scratch, then you should review the [Theme
|
||||
Developer Guide][custom theme].
|
||||
|
||||
### Overriding Template Blocks
|
||||
|
||||
The built-in themes implement many of their parts inside template blocks which
|
||||
can be individually overridden in the `main.html` template. Simply create a
|
||||
`main.html` template file in your `custom_dir` and define replacement blocks
|
||||
within that file. Just make sure that the `main.html` extends `base.html`. For
|
||||
example, to alter the title of the MkDocs theme, your replacement `main.html`
|
||||
template would contain the following:
|
||||
|
||||
```django
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block htmltitle %}
|
||||
<title>Custom title goes here</title>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
In the above example, the `htmltitle` block defined in your custom `main.html` file
|
||||
will be used in place of the default `htmltitle` block defined in the parent theme.
|
||||
You may re-define as many blocks as you desire, as long as those blocks are
|
||||
defined in the parent. For example, you could replace the Google Analytics
|
||||
script with one for a different service or replace the search feature with your
|
||||
own. You will need to consult the parent theme you are using to determine what
|
||||
blocks are available to override. The MkDocs and ReadTheDocs themes provide the
|
||||
following blocks:
|
||||
|
||||
* `site_meta`: Contains meta tags in the document head.
|
||||
* `htmltitle`: Contains the page title in the document head.
|
||||
* `styles`: Contains the link tags for stylesheets.
|
||||
* `libs`: Contains the JavaScript libraries (jQuery, etc) included in the page header.
|
||||
* `scripts`: Contains JavaScript scripts which should execute after a page loads.
|
||||
* `analytics`: Contains the analytics script.
|
||||
* `extrahead`: An empty block in the `<head>` to insert custom tags/scripts/etc.
|
||||
* `site_name`: Contains the site name in the navigation bar.
|
||||
* `site_nav`: Contains the site navigation in the navigation bar.
|
||||
* `search_button`: Contains the search box in the navigation bar.
|
||||
* `next_prev`: Contains the next and previous buttons in the navigation bar.
|
||||
* `repo`: Contains the repository link in the navigation bar.
|
||||
* `content`: Contains the page content and table of contents for the page.
|
||||
* `footer`: Contains the page footer.
|
||||
|
||||
You may need to view the source template files to ensure your modifications will
|
||||
work with the structure of the site. See [Template Variables] for a list of
|
||||
variables you can use within your custom blocks. For a more complete
|
||||
explanation of blocks, consult the [Jinja documentation].
|
||||
|
||||
### Combining the custom_dir and Template Blocks
|
||||
|
||||
Adding a JavaScript library to the `custom_dir` will make it available, but
|
||||
won't include it in the pages generated by MkDocs. Therefore, a link needs to
|
||||
be added to the library from the HTML.
|
||||
|
||||
Starting the with directory structure above (truncated):
|
||||
|
||||
```nohighlight
|
||||
- docs/
|
||||
- custom_theme/
|
||||
- js/
|
||||
- somelib.js
|
||||
- config.yml
|
||||
```
|
||||
|
||||
A link to the `custom_theme/js/somelib.js` file needs to be added to the
|
||||
template. As `somelib.js` is a JavaScript library, it would logically go in the
|
||||
`libs` block. However, a new `libs` block that only includes the new script will
|
||||
replace the block defined in the parent template and any links to libraries in
|
||||
the parent template will be removed. To avoid breaking the template, a
|
||||
[super block] can be used with a call to `super` from within the block:
|
||||
|
||||
```django
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block libs %}
|
||||
{{ super() }}
|
||||
<script src="{{ base_url }}/js/somelib.js"></script>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
Note that the [base_url] template variable was used to ensure that the link is
|
||||
always relative to the current page.
|
||||
|
||||
Now the generated pages will include links to the template provided libraries as
|
||||
well as the library included in the `custom_dir`. The same would be required for
|
||||
any additional CSS files included in the `custom_dir`.
|
||||
|
||||
[custom theme]: ../dev-guide/themes.md
|
||||
[extra_css]: ./configuration.md#extra_css
|
||||
[extra_javascript]: ./configuration.md#extra_javascript
|
||||
[documentation directory]: ./configuration.md#docs_dir
|
||||
[ReadTheDocs]: ./deploying-your-docs.md#readthedocs
|
||||
[custom_dir]: ./configuration.md#custom_dir
|
||||
[name]: ./configuration.md#name
|
||||
[mkdocs]: ./choosing-your-theme.md#mkdocs
|
||||
[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
|
||||
[Template Variables]: ../dev-guide/themes.md#template-variables
|
||||
[Jinja documentation]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
|
||||
[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
|
||||
[base_url]: ../dev-guide/themes.md#base_url
|
||||
@@ -132,7 +132,7 @@ public repository.
|
||||
[rtd]: https://readthedocs.org/
|
||||
[instructions]: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html
|
||||
[features]: https://docs.readthedocs.io/en/latest/features.html
|
||||
[theme]: ./styling-your-docs.md#readthedocs
|
||||
[theme]: ./choosing-your-theme.md#readthedocs
|
||||
|
||||
## Other Providers
|
||||
|
||||
|
||||
19
docs/user-guide/index.md
Normal file
19
docs/user-guide/index.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# User Guide
|
||||
|
||||
Building Documentation with MkDocs
|
||||
|
||||
---
|
||||
|
||||
The MkDocs Developer Guide provides documentation for users of MkDocs. See
|
||||
[Getting Started] for an intorductory totorial. You can jump directly to a
|
||||
page listed below, or use the *next* and *previous* buttons in the navigation
|
||||
bar at the top of the page to move through the documention in order.
|
||||
|
||||
- [Installation](installation.md)
|
||||
- [Writing Your Docs](writing-your-docs.md)
|
||||
- [Choosing Your Theme](choosing-your-theme.md)
|
||||
- [Customizing Your Theme](customizing-your-theme.md)
|
||||
- [Configuration](configuration.md)
|
||||
- [Deploying Your Docs](deploying-your-docs.md)
|
||||
|
||||
[Getting Started]: ../getting-started.md
|
||||
104
docs/user-guide/installation.md
Normal file
104
docs/user-guide/installation.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# MkDocs Installation
|
||||
|
||||
A detailed guide.
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
MkDocs requires a recent version of [Python] and the the Python package
|
||||
manager, [pip], to be installed on your system.
|
||||
|
||||
You can check if you already have these installed from the command line:
|
||||
|
||||
```bash
|
||||
$ python --version
|
||||
Python 3.8.2
|
||||
$ pip --version
|
||||
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
|
||||
```
|
||||
|
||||
If you already have those packages installed, you may skip down to [Installing
|
||||
MkDocs](#installing-mkdocs).
|
||||
|
||||
### Installing Python
|
||||
|
||||
Install [Python] using your package manager of choice, or by downloading an
|
||||
installer appropriate for your system from [python.org] and running it.
|
||||
|
||||
!!! Note
|
||||
|
||||
If you are installing Python on Windows, be sure to check the box to have
|
||||
Python added to your PATH if the installer offers such an option (it's
|
||||
normally off by default).
|
||||
|
||||
|
||||
|
||||
### Installing pip
|
||||
|
||||
If you're using a recent version of Python, the Python package manager, [pip],
|
||||
is most likely installed by default. However, you may need to upgrade pip to the
|
||||
lasted version:
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
```
|
||||
|
||||
If you need to install pip for the first time, download [get-pip.py].
|
||||
Then run the following command to install it:
|
||||
|
||||
```bash
|
||||
python get-pip.py
|
||||
```
|
||||
|
||||
## Installing MkDocs
|
||||
|
||||
Install the `mkdocs` package using pip:
|
||||
|
||||
```bash
|
||||
pip install mkdocs
|
||||
```
|
||||
|
||||
You should now have the `mkdocs` command installed on your system. Run `mkdocs
|
||||
--version` to check that everything worked okay.
|
||||
|
||||
```bash
|
||||
$ mkdocs --version
|
||||
mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8)
|
||||
```
|
||||
|
||||
!!! Note
|
||||
If you would like manpages installed for MkDocs, the [click-man] tool can
|
||||
generate and install them for you. Simply run the following two commands:
|
||||
|
||||
pip install click-man
|
||||
click-man --target path/to/man/pages mkdocs
|
||||
|
||||
See the [click-man documentation] for an explanation of why manpages are
|
||||
not automatically generated and installed by pip.
|
||||
|
||||
!!! Note
|
||||
If you are using Windows, some of the above commands may not work
|
||||
out-of-the-box.
|
||||
|
||||
A quick solution may be to preface every Python command with `python -m`
|
||||
like this:
|
||||
|
||||
python -m pip install mkdocs
|
||||
python -m mkdocs
|
||||
|
||||
For a more permanent solution, you may need to edit your `PATH` environment
|
||||
variable to include the `Scripts` directory of your Python installation.
|
||||
Recent versions of Python include a script to do this for you. Navigate to
|
||||
your Python installation directory (for example `C:\Python38\`), open the
|
||||
`Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
|
||||
clicking on it. Alternatively, you can download the [script][a2p] and run it
|
||||
(`python win_add2path.py`).
|
||||
|
||||
[Python]: https://www.python.org/
|
||||
[python.org]: https://www.python.org/downloads/
|
||||
[pip]: https://pip.readthedocs.io/en/stable/installing/
|
||||
[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
|
||||
[click-man]: https://github.com/click-contrib/click-man
|
||||
[click-man documentation]: https://github.com/click-contrib/click-man#automatic-man-page-installation-with-setuptools-and-pip
|
||||
[a2p]: https://github.com/python/cpython/blob/master/Tools/scripts/win_add2path.py
|
||||
@@ -1,373 +0,0 @@
|
||||
# Styling your docs
|
||||
|
||||
How to style and theme 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's [custom_dir]. You can also
|
||||
create your own [custom theme] from the ground 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] listed 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
|
||||
|
||||
### mkdocs
|
||||
|
||||
The default theme, which was built as a custom [Bootstrap] theme, supports most
|
||||
every feature of MkDocs.
|
||||
|
||||
|
||||
|
||||
In addition to the default [theme configuration options], the `mkdocs` theme
|
||||
supports the following options:
|
||||
|
||||
* __`highlightjs`__: Enables highlighting of source code in code blocks using
|
||||
the [highlight.js] JavaScript library. Default: `True`.
|
||||
|
||||
* __`hljs_style`__: The highlight.js library provides 79 different [styles]
|
||||
(color variations) for highlighting source code in code blocks. Set this to
|
||||
the name of the desired style. Default: `github`.
|
||||
|
||||
* __`hljs_languages`__: By default, highlight.js only supports 23 common
|
||||
languages. List additional languages here to include support for them.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
highlightjs: true
|
||||
hljs_languages:
|
||||
- yaml
|
||||
- rust
|
||||
|
||||
* __`shortcuts`__: Defines keyboard shortcut keys.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
shortcuts:
|
||||
help: 191 # ?
|
||||
next: 78 # n
|
||||
previous: 80 # p
|
||||
search: 83 # s
|
||||
|
||||
All values must be numeric key codes. It is best to use keys which are
|
||||
available on all keyboards. You may use <https://keycode.info/> to determine
|
||||
the key code for a given key.
|
||||
|
||||
* __`help`__: Display a help modal which lists the keyboard shortcuts.
|
||||
Default: `191` (?)
|
||||
|
||||
* __`next`__: Navigate to the "next" page. Default: `78` (n)
|
||||
|
||||
* __`previous`__: Navigate to the "previous" page. Default: `80` (p)
|
||||
|
||||
* __`search`__: Display the search modal. Default: `83` (s)
|
||||
|
||||
* __`navigation_depth`__: The maximum depth of the navigation tree in the
|
||||
sidebar. Default: `2`.
|
||||
|
||||
* __`nav_style`__: This adjusts the visual style for the top navigation bar; by
|
||||
default, this is set to `primary` (the default), but it can also be set to
|
||||
`dark` or `light`.
|
||||
|
||||
theme:
|
||||
name: mkdocs
|
||||
nav_style: dark
|
||||
|
||||
[styles]: https://highlightjs.org/static/demo/
|
||||
|
||||
### readthedocs
|
||||
|
||||
A clone of the default theme used by the [Read the Docs] service, which offers
|
||||
the same restricted feature-set as its parent theme. Like its parent theme, only
|
||||
two levels of navigation are supported.
|
||||
|
||||
|
||||
|
||||
In addition to the default [theme configuration options], the `readthedocs`
|
||||
theme supports the following options:
|
||||
|
||||
* __`highlightjs`__: Enables highlighting of source code in code blocks using
|
||||
the [highlight.js] JavaScript library. Default: `True`.
|
||||
|
||||
* __`hljs_languages`__: By default, highlight.js only supports 23 common
|
||||
languages. List additional languages here to include support for them.
|
||||
|
||||
theme:
|
||||
name: readthedocs
|
||||
highlightjs: true
|
||||
hljs_languages:
|
||||
- yaml
|
||||
- rust
|
||||
|
||||
* __`include_homepage_in_sidebar`__: Lists the homepage in the sidebar menu. As
|
||||
MkDocs requires that the homepage be listed in the `nav` configuration
|
||||
option, this setting allows the homepage to be included or excluded from
|
||||
the sidebar. Note that the site name/logo always links to the homepage.
|
||||
Default: `True`.
|
||||
|
||||
* __`prev_next_buttons_location`__: One of `bottom`, `top`, `both` , or `none`.
|
||||
Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`.
|
||||
|
||||
* __`navigation_depth`__: The maximum depth of the navigation tree in the
|
||||
sidebar. Default: `4`.
|
||||
|
||||
* __`collapse_navigation`__: Only include the page section headers in the
|
||||
sidebar for the current page. Default: `True`.
|
||||
|
||||
* __`titles_only`__: Only include page titles in the sidebar, excluding all
|
||||
section headers for all pages. Default: `False`.
|
||||
|
||||
* __`sticky_navigation`__: If True, causes the sidebar to scroll with the main
|
||||
page content as you scroll the page. Default: `True`.
|
||||
|
||||
### Third Party 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.
|
||||
|
||||
## 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
|
||||
[custom_dir] setting.
|
||||
|
||||
### Using the docs_dir
|
||||
|
||||
The [extra_css] and [extra_javascript] configuration options can be used to
|
||||
make tweaks and customizations to existing themes. To use these, you simply
|
||||
need to include either CSS or JavaScript files within your [documentation
|
||||
directory].
|
||||
|
||||
For example, to change the colour of the headers in your documentation, create
|
||||
a file called `extra.css` and place it next to the documentation Markdown. In
|
||||
that file add the following CSS.
|
||||
|
||||
```CSS
|
||||
h1 {
|
||||
color: red;
|
||||
}
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
||||
If you are deploying your documentation with [ReadTheDocs]. You will need
|
||||
to explicitly list the CSS and JavaScript files you want to include in
|
||||
your config. To do this, add the following to your mkdocs.yml.
|
||||
|
||||
extra_css: [extra.css]
|
||||
|
||||
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 success including the library by using the
|
||||
theme [custom_dir].
|
||||
|
||||
### Using the theme custom_dir
|
||||
|
||||
The theme.[custom_dir] configuration option can be used to point to a directory
|
||||
of files which override the files in a parent theme. The parent theme would be
|
||||
the theme defined in the theme.[name] configuration option. Any file in the
|
||||
`custom_dir` with the same name as a file in the parent theme will replace the
|
||||
file of the same name in the parent theme. Any additional files in the
|
||||
`custom_dir` will be added to the parent theme. The contents of the `custom_dir`
|
||||
should mirror the directory structure of the parent theme. You may include
|
||||
templates, JavaScript files, CSS files, images, fonts, or any other media
|
||||
included in a theme.
|
||||
|
||||
!!! Note
|
||||
|
||||
For this to work, the theme `name` setting must be set to a known installed theme.
|
||||
If the `name` setting is instead set to `null` (or not defined), then there
|
||||
is no theme to override and the contents of the `custom_dir` must be a
|
||||
complete, standalone theme. See [Custom Themes][custom theme] for more
|
||||
information.
|
||||
|
||||
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:
|
||||
name: mkdocs
|
||||
custom_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 parent theme (defined in `name`) but not included
|
||||
in the `custom_dir` will still be utilized. The `custom_dir` will only
|
||||
override/replace files in the parent theme. If you want to remove files, or
|
||||
build a theme from scratch, then you should review the documentation for
|
||||
building a [custom theme].
|
||||
|
||||
#### Overriding Template Blocks
|
||||
|
||||
The built-in themes implement many of their parts inside template blocks which
|
||||
can be individually overridden in the `main.html` template. Simply create a
|
||||
`main.html` template file in your `custom_dir` and define replacement blocks
|
||||
within that file. Just make sure that the `main.html` extends `base.html`. For
|
||||
example, to alter the title of the MkDocs theme, your replacement `main.html`
|
||||
template would contain the following:
|
||||
|
||||
```django
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block htmltitle %}
|
||||
<title>Custom title goes here</title>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
In the above example, the `htmltitle` block defined in your custom `main.html` file
|
||||
will be used in place of the default `htmltitle` block defined in the parent theme.
|
||||
You may re-define as many blocks as you desire, as long as those blocks are
|
||||
defined in the parent. For example, you could replace the Google Analytics
|
||||
script with one for a different service or replace the search feature with your
|
||||
own. You will need to consult the parent theme you are using to determine what
|
||||
blocks are available to override. The MkDocs and ReadTheDocs themes provide the
|
||||
following blocks:
|
||||
|
||||
* `site_meta`: Contains meta tags in the document head.
|
||||
* `htmltitle`: Contains the page title in the document head.
|
||||
* `styles`: Contains the link tags for stylesheets.
|
||||
* `libs`: Contains the JavaScript libraries (jQuery, etc) included in the page header.
|
||||
* `scripts`: Contains JavaScript scripts which should execute after a page loads.
|
||||
* `analytics`: Contains the analytics script.
|
||||
* `extrahead`: An empty block in the `<head>` to insert custom tags/scripts/etc.
|
||||
* `site_name`: Contains the site name in the navigation bar.
|
||||
* `site_nav`: Contains the site navigation in the navigation bar.
|
||||
* `search_button`: Contains the search box in the navigation bar.
|
||||
* `next_prev`: Contains the next and previous buttons in the navigation bar.
|
||||
* `repo`: Contains the repository link in the navigation bar.
|
||||
* `content`: Contains the page content and table of contents for the page.
|
||||
* `footer`: Contains the page footer.
|
||||
|
||||
You may need to view the source template files to ensure your modifications will
|
||||
work with the structure of the site. See [Template Variables] for a list of
|
||||
variables you can use within your custom blocks. For a more complete
|
||||
explanation of blocks, consult the [Jinja documentation].
|
||||
|
||||
#### Combining the custom_dir and Template Blocks
|
||||
|
||||
Adding a JavaScript library to the `custom_dir` will make it available, but
|
||||
won't include it in the pages generated by MkDocs. Therefore, a link needs to
|
||||
be added to the library from the HTML.
|
||||
|
||||
Starting the with directory structure above (truncated):
|
||||
|
||||
```nohighlight
|
||||
- docs/
|
||||
- custom_theme/
|
||||
- js/
|
||||
- somelib.js
|
||||
- config.yml
|
||||
```
|
||||
|
||||
A link to the `custom_theme/js/somelib.js` file needs to be added to the
|
||||
template. As `somelib.js` is a JavaScript library, it would logically go in the
|
||||
`libs` block. However, a new `libs` block that only includes the new script will
|
||||
replace the block defined in the parent template and any links to libraries in
|
||||
the parent template will be removed. To avoid breaking the template, a
|
||||
[super block] can be used with a call to `super` from within the block:
|
||||
|
||||
```django
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block libs %}
|
||||
{{ super() }}
|
||||
<script src="{{ base_url }}/js/somelib.js"></script>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
Note that the [base_url] template variable was used to ensure that the link is
|
||||
always relative to the current page.
|
||||
|
||||
Now the generated pages will include links to the template provided libraries as
|
||||
well as the library included in the `custom_dir`. The same would be required for
|
||||
any additional CSS files included in the `custom_dir`.
|
||||
|
||||
[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
|
||||
[built-in themes]: #built-in-themes
|
||||
[Bootstrap]: https://getbootstrap.com/
|
||||
[theme configuration options]: ./configuration.md#theme
|
||||
[Read the Docs]: https://readthedocs.org/
|
||||
[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
|
||||
[custom theme]: ./custom-themes.md
|
||||
[customize]: #customizing-a-theme
|
||||
[docs_dir]: #using-the-docs_dir
|
||||
[documentation directory]: ./configuration.md#docs_dir
|
||||
[extra_css]: ./configuration.md#extra_css
|
||||
[extra_javascript]: ./configuration.md#extra_javascript
|
||||
[Jinja documentation]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
|
||||
[mkdocs]: #mkdocs
|
||||
[ReadTheDocs]: ./deploying-your-docs.md#readthedocs
|
||||
[Template Variables]: ./custom-themes.md#template-variables
|
||||
[custom_dir]: ./configuration.md#custom_dir
|
||||
[name]: ./configuration.md#name
|
||||
[third party themes]: #third-party-themes
|
||||
[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
|
||||
[base_url]: ./custom-themes.md#base_url
|
||||
[highlight.js]: https://highlightjs.org/
|
||||
17
mkdocs.yml
17
mkdocs.yml
@@ -15,13 +15,19 @@ theme:
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Getting Started: getting-started.md
|
||||
- User Guide:
|
||||
- Overview: user-guide/index.md
|
||||
- Installation: user-guide/installation.md
|
||||
- Writing Your Docs: user-guide/writing-your-docs.md
|
||||
- Styling Your Docs: user-guide/styling-your-docs.md
|
||||
- Choosing Your Theme: user-guide/choosing-your-theme.md
|
||||
- Customizing Your Theme: user-guide/customizing-your-theme.md
|
||||
- Configuration: user-guide/configuration.md
|
||||
- Deploying Your Docs: user-guide/deploying-your-docs.md
|
||||
- Custom Themes: user-guide/custom-themes.md
|
||||
- Plugins: user-guide/plugins.md
|
||||
- Developer Guide:
|
||||
- Overview: dev-guide/index.md
|
||||
- Themes: dev-guide/themes.md
|
||||
- Plugins: dev-guide/plugins.md
|
||||
- About:
|
||||
- Release Notes: about/release-notes.md
|
||||
- Contributing: about/contributing.md
|
||||
@@ -44,3 +50,8 @@ google_analytics: ['UA-27795084-5', 'mkdocs.org']
|
||||
|
||||
plugins:
|
||||
- search
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
user-guide/plugins.md: dev-guide/plugins.md
|
||||
user-guide/custom-themes.md: dev-guide/themes.md
|
||||
user-guide/styling-your-docs.md: user-guide/choosing-your-theme.md
|
||||
|
||||
@@ -3,7 +3,8 @@ Jinja2==2.10.1
|
||||
livereload==2.5.1
|
||||
Markdown==3.2.1
|
||||
PyYAML==5.1
|
||||
tornado==4.1
|
||||
tornado==5.0
|
||||
mdx_gh_links==0.2
|
||||
ghp-import==1.0
|
||||
pyyaml_env_tag==0.1
|
||||
mkdocs-redirects==1.0.1
|
||||
|
||||
@@ -7,3 +7,4 @@ tornado>=5.1.1
|
||||
mdx_gh_links>=0.2
|
||||
ghp-import>=1.0
|
||||
pyyaml_env_tag>=0.1
|
||||
mkdocs-redirects>=1.0.1
|
||||
|
||||
Reference in New Issue
Block a user