`),
do:
```yaml
markdown_extensions:
- toc:
baselevel: 2
```
Then any headers in your document would be increased by 1. For example, the
header `# Header` would be rendered as a level 2 header (`
`) in the HTML
output.
* **`separator`**
Word separator. Default: `-`.
Character which replaces white-space in generated IDs. If you prefer
underscores, then do:
```yaml
markdown_extensions:
- toc:
separator: "_"
```
Note that if you would like to define multiple of the above settings, you must
do so under a single `toc` entry in the `markdown_extensions` configuration
option.
```yml
markdown_extensions:
- toc:
permalink: "#"
baselevel: 2
separator: "_"
```
[toc]: https://python-markdown.github.io/extensions/toc/
#### Linking to images and media
As well as the Markdown source files, you can also include other file types in
your documentation, which will be copied across when generating your
documentation site. These might include images and other media.
For example, if your project documentation needed to include a [GitHub Pages
CNAME file] and a PNG formatted screenshot image then your file layout might
look as follows:
```text
mkdocs.yml
docs/
CNAME
index.md
about.md
license.md
img/
screenshot.png
```
To include images in your documentation source files, simply use any of the
regular Markdown image syntaxes:
```Markdown
Cupcake indexer is a snazzy new project for indexing small cakes.

*Above: Cupcake indexer in progress*
```
Your image will now be embedded when you build the documentation, and should
also be previewed if you're working on the documentation with a Markdown editor.
[GitHub Pages CNAME file]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
#### Linking from raw HTML
Markdown allows document authors to fall back to raw HTML when the Markdown
syntax does not meets the author's needs. MkDocs does not limit Markdown in this
regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is
not able to validate or convert links contained in raw HTML. When including
internal links within raw HTML, you will need to manually format the link
appropriately for the rendered document.
### Meta-Data
MkDocs includes support for both YAML and MultiMarkdown style meta-data (often
called front-matter). Meta-data consists of a series of keywords and values
defined at the beginning of a Markdown document, which are stripped from the
document prior to it being processing by Python-Markdown. The key/value pairs
are passed by MkDocs to the page template. Therefore, if a theme includes
support, the values of any keys can be displayed on the page or used to control
the page rendering. See your theme's documentation for information about which
keys may be supported, if any.
In addition to displaying information in a template, MkDocs includes support for
a few predefined meta-data keys which can alter the behavior of MkDocs for that
specific page. The following keys are supported:
* **`template`**
The template to use with the current page.
By default, MkDocs uses the `main.html` template of a theme to render
Markdown pages. You can use the `template` meta-data key to define a
different template file for that specific page. The template file must be
available on the path(s) defined in the theme's environment.
* **`title`**
The "title" to use for the document.
MkDocs will attempt to determine the title of a document in the following
ways, in order:
1. A title defined in the [nav] configuration setting for a document.
2. A title defined in the `title` meta-data key of a document.
3. A level 1 Markdown header on the first line of the document body.
([Setext-style] headers are supported *only since MkDocs 1.5*.)
4. The filename of a document.
Upon finding a title for a page, MkDoc does not continue checking any
additional sources in the above list.
[Setext-style]: https://daringfireball.net/projects/markdown/syntax#header
#### YAML Style Meta-Data
YAML style meta-data consists of [YAML] key/value pairs wrapped in YAML style
delimiters to mark the start and/or end of the meta-data. The first line of
a document must be `---`. The meta-data ends at the first line containing an
end deliminator (either `---` or `...`). The content between the delimiters is
parsed as [YAML].
```text
---
title: My Document
summary: A brief description of my document.
authors:
- Waylan Limberg
- Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.
```
YAML is able to detect data types. Therefore, in the above example, the values
of `title`, `summary` and `some_url` are strings, the value of `authors` is a
list of strings and the value of `date` is a `datetime.date` object. Note that
the YAML keys are case sensitive and MkDocs expects keys to be all lowercase.
The top level of the YAML must be a collection of key/value pairs, which results
in a Python `dict` being returned. If any other type is returned or the YAML
parser encounters an error, then MkDocs does not recognize the section as
meta-data, the page's `meta` attribute will be empty, and the section is not
removed from the document.
#### MultiMarkdown Style Meta-Data
MultiMarkdown style meta-data uses a format first introduced by the
[MultiMarkdown] project. The data consists of a series of keywords and values
defined at the beginning of a Markdown document, like this:
```text
Title: My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
Tom Christie
Date: January 23, 2018
blank-value:
some_url: https://example.com
This is the first paragraph of the document.
```
The keywords are case-insensitive and may consist of letters, numbers,
underscores and dashes and must end with a colon. The values consist of anything
following the colon on the line and may even be blank.
If a line is indented by 4 or more spaces, that line is assumed to be an
additional line of the value for the previous keyword. A keyword may have as
many lines as desired. All lines are joined into a single string.
The first blank line ends all meta-data for the document. Therefore, the first
line of a document must not be blank.
NOTE:
MkDocs does not support YAML style delimiters (`---` or `...`) for
MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or
absence of the delimiters to determine whether YAML style meta-data or
MultiMarkdown style meta-data is being used. If the delimiters are
detected, but the content between the delimiters is not valid YAML
meta-data, MkDocs does not attempt to parse the content as MultiMarkdown
style meta-data.
[YAML]: https://yaml.org
[MultiMarkdown]: https://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
[nav]: configuration.md#nav
### Tables
The [tables] extension adds a basic table syntax to Markdown which is popular
across multiple implementations. The syntax is rather simple and is generally
only useful for simple tabular data.
A simple table looks like this:
```markdown
First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell | Content Cell
Content Cell | Content Cell | Content Cell
```
If you wish, you can add a leading and tailing pipe to each line of the table:
```markdown
| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell | Content Cell |
| Content Cell | Content Cell | Content Cell |
```
Specify alignment for each column by adding colons to separator lines:
```markdown
First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left | Center | Right
Left | Center | Right
```
Note that table cells cannot contain any block level elements and cannot contain
multiple lines of text. They can, however, include inline Markdown as defined in
Markdown's [syntax] rules.
Additionally, a table must be surrounded by blank lines. There must be a blank
line before and after the table.
[tables]: https://python-markdown.github.io/extensions/tables/
### Fenced code blocks
The [fenced code blocks] extension adds an alternate method of defining code
blocks without indentation.
The first line should contain 3 or more backtick (`` ` ``) characters, and the
last line should contain the same number of backtick characters (`` ` ``):
````markdown
```
Fenced code blocks are like Standard
Markdown’s regular code blocks, except that
they’re not indented and instead rely on
start and end fence lines to delimit the
code block.
```
````
With this approach, the language can optionally be specified on the first line
after the backticks which informs any syntax highlighters of the language used:
````markdown
```python
def fn():
pass
```
````
Note that fenced code blocks can not be indented. Therefore, they cannot be
nested inside list items, blockquotes, etc.
[fenced code blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
mkdocs-1.6.1/docs/user-guide/cli.md 0000664 0001750 0001750 00000000237 14664334534 016771 0 ustar carsten carsten # Command Line Interface
::: mkdocs-click
:module: mkdocs.__main__
:command: cli
:prog_name: mkdocs
:style: table
:list_subcommands: true
mkdocs-1.6.1/docs/user-guide/customizing-your-theme.md 0000664 0001750 0001750 00000020164 14664334534 022672 0 ustar carsten carsten # 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 color of the headers in your documentation, create
a file called (for example) `style.css` and place it next to the documentation Markdown. In
that file add the following CSS.
```css
h1 {
color: red;
}
```
Then you need to add it to `mkdocs.yml`:
```yaml
extra_css:
- style.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):
```text
- 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:
```text
- 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 %}
Custom title goes here
{% 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 `` 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):
```text
- 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() }}
{% 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
[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]: https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance
[super block]: https://jinja.palletsprojects.com/en/latest/templates/#super-blocks
[base_url]: ../dev-guide/themes.md#base_url
mkdocs-1.6.1/docs/user-guide/README.md 0000664 0001750 0001750 00000001347 14664334534 017162 0 ustar carsten carsten # User Guide
Building Documentation with MkDocs
---
The MkDocs User Guide provides documentation for users of MkDocs. See
[Getting Started] for an introductory tutorial. 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 documentation 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)
- [Localizing Your Theme](localizing-your-theme.md)
- [Configuration](configuration.md)
- [Command Line Interface](cli.md)
- [Deploying Your Docs](deploying-your-docs.md)
[Getting Started]: ../getting-started.md
mkdocs-1.6.1/docs/user-guide/installation.md 0000664 0001750 0001750 00000006235 14664334534 020727 0 ustar carsten carsten # MkDocs Installation
A detailed guide.
---
## Requirements
MkDocs requires a recent version of [Python] and the Python package
manager, [pip], to be installed on your system.
You can check if you already have these installed from the command line:
```console
$ 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.
```console
$ 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:
>
> ```bash
> 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:
>
> ```bash
> 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
mkdocs-1.6.1/docs/user-guide/deploying-your-docs.md 0000664 0001750 0001750 00000022332 14664334534 022136 0 ustar carsten carsten # Deploying your docs
A basic guide to deploying your docs to various hosting providers
---
## GitHub Pages
If you host the source code for a project on [GitHub], you can easily use
[GitHub Pages] to host the documentation for your project. There are two basic
[types of GitHub Pages sites]: Project Pages sites, and User and Organization
Pages sites. They are nearly identical but have some important differences,
which require a different work flow when deploying.
### Project Pages
Project Pages sites are simpler as the site files get deployed to a branch
within the project repository (`gh-pages` by default). After you `checkout` the
primary working branch (usually `master`) of the git repository where you
maintain the source documentation for your project, run the following command:
```sh
mkdocs gh-deploy
```
That's it! Behind the scenes, MkDocs will build your docs and use the
[ghp-import] tool to commit them to the `gh-pages` branch and push the
`gh-pages` branch to GitHub.
Use `mkdocs gh-deploy --help` to get a full list of options available for the
`gh-deploy` command.
Be aware that you will not be able to review the built site before it is pushed
to GitHub. Therefore, you may want to verify any changes you make to the docs
beforehand by using the `build` or `serve` commands and reviewing the built
files locally.
WARNING:
You should never edit files in your pages repository by hand if you're using
the `gh-deploy` command because you will lose your work the next time you
run the command.
WARNING:
If there are untracked files or uncommitted work in the local repository where
`mkdocs gh-deploy` is run, these will be included in the pages that are deployed.
### Organization and User Pages
User and Organization Pages sites are not tied to a specific project, and the
site files are deployed to the `master` branch in a dedicated repository named
with the GitHub account name. Therefore, you need working copies of two
repositories on our local system. For example, consider the following file
structure:
```text
my-project/
mkdocs.yml
docs/
orgname.github.io/
```
After making and verifying updates to your project you need to change
directories to the `orgname.github.io` repository and call the
`mkdocs gh-deploy` command from there:
```sh
cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
```
Note that you need to explicitly point to the `mkdocs.yml` configuration file as
it is no longer in the current working directory. You also need to inform the
deploy script to commit to the `master` branch. You may override the default
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.
### Custom Domains
GitHub Pages includes support for using a [Custom Domain] for your site. In
addition to the steps documented by GitHub, you need to take one additional step
so that MkDocs will work with your custom domain. You need to add a `CNAME` file
to the root of your [docs_dir]. The file must contain a single bare domain or
subdomain on a single line (see MkDocs' own [CNAME file] as an example). You may
create the file manually, or use GitHub's web interface to set up the custom
domain (under Settings / Custom Domain). If you use the web interface, GitHub
will create the `CNAME` file for you and save it to the root of your "pages"
branch. So that the file does not get removed the next time you deploy, you need
to copy the file to your `docs_dir`. With the file properly included in your
`docs_dir`, MkDocs will include the file in your built site and push it to your
"pages" branch each time you run the `gh-deploy` command.
If you are having problems getting a custom domain to work, see GitHub's
documentation on [Troubleshooting custom domains].
[GitHub]: https://github.com/
[GitHub Pages]: https://pages.github.com/
[types of GitHub Pages sites]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
[ghp-import]: https://github.com/davisp/ghp-import
[remote_branch]: ./configuration.md#remote_branch
[Custom Domain]: https://help.github.com/articles/adding-or-removing-a-custom-domain-for-your-github-pages-site
[docs_dir]: ./configuration.md#docs_dir
[CNAME file]: https://github.com/mkdocs/mkdocs/blob/master/docs/CNAME
[Troubleshooting custom domains]: https://help.github.com/articles/troubleshooting-custom-domains/
## Read the Docs
[Read the Docs][rtd] offers free documentation hosting. You can import your docs
using the Git version control system. Read the Docs supports MkDocs out-of-the-box.
Follow the [instructions] on their site to arrange the files in your repository properly,
create an account and point it at your publicly hosted repository. If properly
configured, your documentation will update each time you push commits to your
public repository.
[rtd]: https://readthedocs.org/
[instructions]: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html
## Other Providers
Any hosting provider which can serve static files can be used to serve
documentation generated by MkDocs. While it would be impossible to document how
to upload the docs to every hosting provider out there, the following guidelines
should provide some general assistance.
When you build your site (using the `mkdocs build` command), all of the files
are written to the directory assigned to the [site_dir] configuration option
(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
simply need to copy the contents of that directory to the root directory of your
hosting provider's server. Depending on your hosting provider's setup, you may
need to use a graphical or command line [ftp], [ssh] or [scp] client to transfer
the files.
For example, a typical set of commands from the command line might look
something like this:
```sh
mkdocs build
scp -r ./site user@host:/path/to/server/root
```
Of course, you will need to replace `user` with the username you have with your
hosting provider and `host` with the appropriate domain name. Additionally, you
will need to adjust the `/path/to/server/root` to match the configuration of
your hosts' file system.
[ftp]: https://en.wikipedia.org/wiki/File_Transfer_Protocol
[ssh]: https://en.wikipedia.org/wiki/Secure_Shell
[scp]: https://en.wikipedia.org/wiki/Secure_copy
See your host's documentation for specifics. You will likely want to search
their documentation for "ftp" or "uploading site".
## Local Files
Rather than hosting your documentation on a server, you may instead distribute
the files directly, which can then be viewed in a browser using the `file://`
scheme.
Note that, due to the security settings of all modern browsers, some things
will not work the same and some features may not work at all. In fact, a few
settings will need to be customized in very specific ways.
- [site_url]:
The `site_url` must be set to an empty string, which instructs MkDocs to
build your site so that it will work with the `file://` scheme.
```yaml
site_url: ""
```
- [use_directory_urls]:
Set `use_directory_urls` to `false`. Otherwise, internal links between
pages will not work properly.
```yaml
use_directory_urls: false
```
- [search]:
You will need to either disable the search plugin, or use a third-party
search plugin which is specifically designed to work with the `file://`
scheme. To disable all plugins, set the `plugins` setting to an empty list.
```yaml
plugins: []
```
If you have other plugins enabled, simply ensure that `search` is not
included in the list.
When writing your documentation, it is imperative that all internal links use
relative URLs as [documented][internal links]. Remember, each reader of your
documentation will be using a different device and the files will likely be in a
different location on that device.
If you expect your documentation to be viewed off-line, you may also need to be
careful about which themes you choose. Many themes make use of CDNs for various
support files, which require a live Internet connection. You will need to choose
a theme which includes all support files directly in the theme.
When you build your site (using the `mkdocs build` command), all of the files
are written to the directory assigned to the [site_dir] configuration option
(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
simply need to copy the contents of that directory and distribute it to your
readers. Alternatively, you may choose to use a third party tool to convert the
HTML files to some other documentation format.
## 404 Pages
When MkDocs builds the documentation it will include a 404.html file in the
[build directory][site_dir]. This file will be automatically used when
deploying to [GitHub](#github-pages) but only on a custom domain. Other web
servers may be configured to use it but the feature won't always be available.
See the documentation for your server of choice for more information.
[site_dir]: ./configuration.md#site_dir
[site_url]: ./configuration.md#site_url
[use_directory_urls]: ./configuration.md#use_directory_urls
[search]: ./configuration.md#search
[internal links]: ./writing-your-docs.md#internal-links
mkdocs-1.6.1/docs/user-guide/choosing-your-theme.md 0000664 0001750 0001750 00000020750 14664334534 022131 0 ustar carsten carsten # 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 almost
every feature of MkDocs.
In addition to the default [theme configuration options][theme], the `mkdocs` theme
supports the following options:
* **`color_mode`**: Set the default color mode for the theme to one of `light`,
`dark`, or `auto`. The `auto` mode will switch to `light` or `dark` based on
the system configuration of the user's device. Default: `light`.
* **`user_color_mode_toggle`**: Enable a toggle menu in the navigation bar
which allows users to select their preferred `color_mode` (light, dark, auto)
from within the browser and save their preference for future page loads. The
default selection of the toggle menu on first page load is the value set to
`color_mode`. Default: `false`.

* **`nav_style`**: Adjust the visual style of the top navigation bar. Set to
one of `primary`, `dark` or `light`. Default: `primary`. This option is
independent of the `color_mode` option and must be defined separately.
* **`highlightjs`**: Enables highlighting of source code in code blocks using
the [highlight.js] JavaScript library. Default: `True`.
* **`hljs_style`**: The highlight.js library provides many different [styles]
(color variations) for highlighting source code in code blocks. Set this to
the name of the desired style when in `light` mode. Default: `github`.
* **`hljs_style_dark`**: Set this to the name of the desired highlight.js
style when in `dark` mode. Default: `github_dark`.
* **`hljs_languages`**: By default, highlight.js only supports 23 common
languages. List additional languages here to include support for them.
```yaml
theme:
name: mkdocs
highlightjs: true
hljs_languages:
- yaml
- rust
```
* **`analytics`**: Defines configuration options for an analytics service.
Currently, only Google Analytics v4 is supported via the `gtag` option.
* **`gtag`**: To enable Google Analytics, set to a Google Analytics v4
tracking ID, which uses the `G-` format. See Google's documentation to
[Set up Analytics for a website and/or app (GA4)][setup-GA4] or to
[Upgrade to a Google Analytics 4 property][upgrade-GA4].
```yaml
theme:
name: mkdocs
analytics:
gtag: G-ABC123
```
When set to the default (`null`) Google Analytics is disabled for the
site.
* **`shortcuts`**: Defines keyboard shortcut keys.
```yaml
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 that are
available on all keyboards. You may use to determine
the key code for a given key.
* **`help`**: Display a help modal that 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`.
* **`locale`**{ #mkdocs-locale }: The locale (language/location) used to
build the theme. If your locale is not yet supported, it will fall back
to the default.
The following locales are supported by this theme:
* `en`: English (default)
* (see the list of existing directories `mkdocs/themes/mkdocs/locales/*/`)
See the guide on [localizing your theme] for more information.
## 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.
```yaml
theme:
name: readthedocs
highlightjs: true
hljs_languages:
- yaml
- rust
```
* **`analytics`**: Defines configuration options for an analytics service.
* **`gtag`**: To enable Google Analytics, set to a Google Analytics v4
tracking ID, which uses the `G-` format. See Google's documentation to
[Set up Analytics for a website and/or app (GA4)][setup-GA4] or to
[Upgrade to a Google Analytics 4 property][upgrade-GA4].
```yaml
theme:
name: readthedocs
analytics:
gtag: G-ABC123
```
When set to the default (`null`) Google Analytics is disabled for the
* **`anonymize_ip`**: To enable anonymous IP address for Google Analytics,
set this to `True`. Default: `False`.
* **`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`.
* **`locale`**{ #readthedocs-locale }: The locale (language/location) used to
build the theme. If your locale is not yet supported, it will fall back
to the default.
The following locales are supported by this theme:
* `en`: English (default)
* (see the list of existing directories `mkdocs/themes/readthedocs/locales/*/`)
See the guide on [localizing your theme] for more information.
* **`logo`**: To set a logo on your project instead of the plain text
`site_name`, set this variable to be the location of your image. Default: `null`.
## Third Party Themes
A list of third party themes can be found at the [community wiki] page and [the ranked catalog][catalog]. If you have created your own, please add them there.
WARNING: Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.
[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/
[setup-GA4]: https://support.google.com/analytics/answer/9304153?hl=en&ref_topic=9303319
[upgrade-GA4]: https://support.google.com/analytics/answer/9744165?hl=en&ref_topic=9303319
[Read the Docs]: https://readthedocs.org/
[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
[catalog]: https://github.com/mkdocs/catalog#-theming
[localizing your theme]: localizing-your-theme.md
mkdocs-1.6.1/docs/CNAME 0000664 0001750 0001750 00000000017 14664334534 014371 0 ustar carsten carsten www.mkdocs.org
mkdocs-1.6.1/docs/img/ 0000775 0001750 0001750 00000000000 14664334534 014401 5 ustar carsten carsten mkdocs-1.6.1/docs/img/win-py-install.png 0000664 0001750 0001750 00000100104 14664334534 017772 0 ustar carsten carsten PNG
IHDR P IDATx]&pSX!`
6^nm^V?7[k{ƞw۫m^?v
R%U79u+
ﲸuɷwOGS0,˲s,dҙT*Juvt~gޱͣgrϊo}[9iJR
e2t:c1qV&4-ޑhfluu]w]ljXYD4,c94
gE.\7WȞ96A"gٲN0,+Ҥv
M3R9:^wq՚ίuLty`(-:ҍaoaM7ÙEc`EkbY'ud2N{UwͱS}^yKJ;7-FېV۟k'8yV}sӗ뭩-7_6b?zZϤU'E;k"U4^^}JN{C\hMƽo%O^] Ü6v5;w%:~\7-547Wpa5,esأ,'4 |$bjA@!^ݔ*fT
hMH$P wPa3h0EeDp
K]tL#fņ@ɳ/AOy-2j&&oau<[g:F|.DB>2y<Ħty㣤]ͩ{e2xbMa]/bK~Nu_ݒykԱ]5/pيj݂eKG?v<4ۉ3)XcVu1NyXċ\Tnaܻ5ǻoOYjת5}K?u q 7l/LHh!
_ZrMbO4upGl&XY"|kYQ"AGM ^s%
jr lS-S|+pPSt!n+-DO0]^(y+)o4PC9/<<[uxs-Ζ?sT^71|O=NnoSxumjSmfswg9&pQomn~I Gc_C/|B/)
Fe'BR(D[]7B /a1M
؉@+ 4֠6XoKً̅sgBay{@Cd5m:_H@f$mB{NN|:.aZ!>`girC&:QǚnEܭ,ϬVRsxU+Lܻ~˖ ֫Wy0R;G-\q6`sQmG^G'ݷgèHq_KģyQF[
,% ^(ůgI82`VfER+WPOArY+E8(W YS1 {bOz>~Q^j&m9+O.&d?o߾#G/j=~q/gI5ޕ.y^ꗛ,ĔÏ0a\1xk