Skip to content
Snippets Groups Projects
Commit 4536498c authored by morph027's avatar morph027
Browse files

initial commit

parents
Branches
No related tags found
No related merge requests found
Showing
with 2049 additions and 0 deletions
# Example [MkDocs](http://mkdocs.org/) website using GitLab Pages.
Learn more about GitLab Pages at https://pages.gitlab.io and the official
documentation http://doc.gitlab.com/ee/pages/README.html.
## GitLab CI
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
```
image: python:alpine
before_script:
- pip install mkdocs
# add your custom theme (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) if not inside a theme_dir
# - pip install mkdocs-material
pages:
script:
- mkdocs build
- mv site public
artifacts:
paths:
- public
only:
- master
```
## Building locally
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install](http://www.mkdocs.org/#installation) MkDocs
1. Preview your project: `mkdocs serve`
1. Add content
1. Generate the website: `mkdocs build` (optional)
Read more at MkDocs's [documentation](http://www.mkdocs.org/).
### Preview your site
If you clone or download this project to your local computer and run `mkdocs serve`,
your site can be accessed under `localhost:8000`.
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
You'll need to configure your site too: change this line
in your `mkdocs.yml`, from `"https://pages.gitlab.io/hugo/"` to `site_url = "https://namespace.gitlab.io"`.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
\ No newline at end of file
www.mkdocs.org
# Contributing to MkDocs
An introduction to contributing to the MkDocs project.
The MkDocs project welcomes, and depends, on contributions from developers and
users in the open source community. Contributions can be made in a number of
ways, a few examples are:
- Code patches via pull requests
- Documentation improvements
- Bug reports and patch reviews
## Code of Conduct
Everyone interacting in the MkDocs project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
## Reporting an Issue
Please include as much detail as you can. Let us know your platform and MkDocs
version. If the problem is visual (for example a theme or design issue) please
add a screenshot and if you get an error please include the full error and
traceback.
## Testing the Development Version
If you want to just install and try out the latest development version of
MkDocs you can do so with the following command. This can be useful if you
want to provide feedback for a new feature or want to confirm if a bug you
have encountered is fixed in the git master. It is **strongly** recommended
that you do this within a [virtualenv].
```bash
pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz
```
## Installing for Development
First you'll need to fork and clone the repository. Once you have a local
copy, run the following command. It is **strongly** recommended that you do
this within a [virtualenv].
```bash
pip install --editable .
```
This will install MkDocs in development mode which binds the `mkdocs` command
to the git repository.
## Running the tests
To run the tests, it is recommended that you use [Tox]. This just needs
to be pip installed and then the test suite can be ran for MkDocs but running
the command `tox` in the root of your MkDocs repository.
It will attempt to run the tests against all of the Python versions we
support. So don't be concerned if you are missing some and they fail. The rest
will be verified by [Travis] when you submit a pull request.
## Submitting Pull Requests
Once you are happy with your changes or you are ready for some feedback, push
it to your fork and send a pull request. For a change to be accepted it will
most likely need to have tests and documentation if it is a new feature.
[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html
[tox]: https://tox.readthedocs.io/en/latest/
[travis]: https://travis-ci.org/repositories
[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
# License
The legal stuff.
---
## Included projects
Themes used under license from the ReadTheDocs projects.
* ReadTheDocs theme - [View license](https://github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
Many thanks to the authors and contributors of those wonderful projects.
## MkDocs License (BSD)
Copyright © 2014, Tom Christie. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer. Redistributions in binary form must
reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This diff is collapsed.
div.col-md-9 h1:first-of-type {
text-align: center;
font-size: 60px;
font-weight: 300;
}
div.col-md-9 p:first-of-type {
text-align: center;
}
div.col-md-9 p.admonition-title:first-of-type {
text-align: left;
}
div.col-md-9 h1:first-of-type .headerlink {
display: none;
}
code.no-highlight {
color: black;
}
docs/img/initial-layout.png

18.3 KiB

docs/img/mkdocs.png

158 KiB

docs/img/multipage.png

30.6 KiB

docs/img/readthedocs.png

68.7 KiB

docs/img/screenshot.png

77.9 KiB

docs/img/search.png

99.5 KiB

docs/img/site-name.png

12.9 KiB

docs/img/win-py-install.png

40.7 KiB

# MkDocs
Project documentation with Markdown.
---
!!! Note
This site was built with GitLab Pages!.
Visit this project at [https://gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs).
## 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.
### 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 in the [MkDocs wiki], 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.
---
## 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]: http://brew.sh/
[dnf]: http://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 2.7.2
$ pip --version
pip 1.5.2
```
MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.
#### 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).
![Add Python to PATH](img/win-py-install.png)
[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 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:\Python34\`), 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.
![The initial MkDocs layout](img/initial-layout.png)
There's a single configuration file named `mkdocs.yml`, and a folder named
`docs` that will contain your documentation source files. 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 MkDocs live server](img/screenshot.png)
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.
![The site_name setting](img/site-name.png)
## 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 [`pages`][pages]
setting:
```yaml
site_name: MkLorum
pages:
- 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.
![Screenshot](img/multipage.png)
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 of all that with no effort or configuration on your
part!
![Screenshot](img/search.png)
## 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
pages:
- Home: index.md
- About: about.md
theme: readthedocs
```
Save your changes, and you'll see the ReadTheDocs theme being used.
![Screenshot](img/readthedocs.png)
## Changing the Favicon Icon
By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
an `img` subdirectory in your `docs_dir` and copy your custom `favicon.ico` file
to that directory. MkDocs will automaticaly 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 it's
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. [GitHub project pages] and [Amazon
S3] may be good hosting options, depending upon your needs. 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 [discussion group], [GitHub issues] or
the MkDocs IRC channel `#mkdocs` on freenode.
[deploy]: user-guide/deploying-your-docs/
[mkdocs]: user-guide/styling-your-docs/#mkdocs
[readthedocs]: user-guide/styling-your-docs/#readthedocs
[MkDocs wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
[build your own]: user-guide/custom-themes/
[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
[pages]: user-guide/configuration/#pages
[discussion group]: https://groups.google.com/forum/#!forum/mkdocs
[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually/
[pip]: http://pip.readthedocs.io/en/stable/installing/
[Python]: https://www.python.org/
[site_name]: user-guide/configuration/#site_name
[theme]: user-guide/configuration/#theme
# Configuration
Guide to all available configuration settings.
---
## Introduction
Project settings are always configured by using a YAML configuration file in the
project directory named `mkdocs.yml`.
As a minimum this configuration file must contain the `site_name` setting. All
other settings are optional.
## Project information
### site_name
This is a **required setting**, and should be a string that is used as the main
title for the project documentation. For example:
```yaml
site_name: Marshmallow Generator
```
When rendering the theme this setting will be passed as the `site_name` context
variable.
### site_url
Set the canonical URL of the site. This will add a link tag with the canonical
URL to the generated HTML header.
**default**: `null`
### repo_url
When set, provides a link to your GitHub or Bitbucket repository on each page.
```yaml
repo_url: https://github.com/example/repository/
```
**default**: `null`
### repo_name
When set, provides a link to your GitHub or Bitbucket repository on each page.
**default**: `'GitHub'` or `'Bitbucket'` if the `repo_url` matches those
domains, otherwise `null`
### edit_uri
Path from the base `repo_url` to the docs directory when directly viewing a
page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,
etc), the branch, and the docs directory itself. Mkdocs concatenates `repo_url`
and `edit_uri`, and appends the input path of the page.
When set, provides a link directly to the page in your source repository. This
makes it easier to find and edit the source for the page. If `repo_url` is not
set, this option is ignored.
For example, for a GitHub-hosted repository, the `edit_uri` would be as follows.
(Note the `edit` path and `master` branch...)
```yaml
edit_uri: edit/master/docs/
```
For a Bitbucket-hosted repository, the equivalent `edit_uri` would be as
follows. (Note the `src` path and `default` branch...)
```yaml
edit_uri: src/default/docs/
```
For other repository hosts, `edit_uri` works the same way. Simply specify the
relative path to the docs directory.
**default**: `edit/master/docs/` or `src/default/docs/` for GitHub or Bitbucket
repos, respectively, if `repo_url` matches those domains, otherwise `null`
!!! note "Note:"
On GitHub, the `edit` path opens the page in the online GitHub editor. This
functionality requires that the user have and be logged in to a GitHub
account. Otherwise, the user will be redirected to a login/signup page.
Alternatively, use the `blob` path to open a read-only view, which supports
anonymous access. E.g. `blob/master/docs/`
### site_description
Set the site description. This will add a meta tag to the generated HTML header.
**default**: `null`
### site_author
Set the name of the author. This will add a meta tag to the generated HTML
header.
**default**: `null`
### copyright
Set the copyright information to be included in the documentation by the theme.
**default**: `null`
### google_analytics
Set the Google analytics tracking configuration.
```yaml
google_analytics: ['UA-36723568-3', 'mkdocs.org']
```
**default**: `null`
### remote_branch
Set the remote branch to commit to when using `gh-deploy` to deploy to Github
Pages. This option can be overridden by a command line option in `gh-deploy`.
**default**: `gh-pages`
### remote_name
Set the remote name to push to when using `gh-deploy` to deploy to Github Pages.
This option can be overridden by a command line option in `gh-deploy`.
**default**: `origin`
## Documentation layout
### pages
This setting is used to determine the set of pages that should be built for the
documentation. For example, the following would create Introduction, User Guide
and About pages, given the three source files `index.md`, `user-guide.md` and
`about.md`, respectively.
```yaml
pages:
- 'Introduction': 'index.md'
- 'User Guide': 'user-guide.md'
- 'About': 'about.md'
```
See the section on [configuring pages and navigation] for a more detailed
breakdown, including how to create sub-sections.
**default**: By default `pages` will contain an alphanumerically sorted, nested
list of all the Markdown files found within the `docs_dir` and its
sub-directories. If none are found it will be `[]` (an empty list).
## Build directories
### theme
Sets the theme of your documentation site, for a list of available themes visit
[styling your docs].
**default**: `'mkdocs'`
### theme_dir
Lets you set a directory to a custom theme. This can either be a relative
directory, in which case it is resolved relative to the directory containing
your configuration file, or it can be an absolute directory path.
See [styling your docs][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.
**default**: `null`
### docs_dir
Lets you set the directory containing the documentation source markdown files.
This can either be a relative directory, in which case it is resolved relative
to the directory containing you configuration file, or it can be an absolute
directory path.
**default**: `'docs'`
### site_dir
Lets you set the directory where the output HTML and other files are created.
This can either be a relative directory, in which case it is resolved relative
to the directory containing you configuration file, or it can be an absolute
directory path.
**default**: `'site'`
!!! note "Note:"
If you are using source code control you will normally want to ensure that
your *build output* files are not committed into the repository, and only
keep the *source* files under version control. For example, if using `git`
you might add the following line to your `.gitignore` file:
site/
If you're using another source code control tool, you'll want to check its
documentation on how to ignore specific directories.
### extra_css
Set a list of CSS files in your `docs_dir` to be included by the theme. For
example, the following example will include the the extra.css file within the
css subdirectory in your [docs_dir](#docs_dir).
```yaml
extra_css:
- css/extra.css
- css/second_extra.css
```
**default**: `[]` (an empty list).
### extra_javascript
Set a list of JavaScript files in your `docs_dir` to be included by the theme.
See the example in [extra_css] for usage.
**default**: `[]` (an empty list).
### extra_templates
Set a list of templates in your `docs_dir` to be built by MkDocs. To see more
about writing templates for MkDocs read the documentation about [custom themes]
and specifically the section about the [variables that are available] to
templates. See the example in [extra_css] for usage.
**default**: `[]` (an empty list).
### extra
A set of key value pairs, where the values can be any valid YAML construct, that
will be passed to the template. This allows for great flexibility when creating
custom themes.
For example, if you are using a theme that supports displaying the project
version, you can pass it to the theme like this:
```yaml
extra:
version: 1.0
```
**default**: By default `extra` will be an empty key value mapping.
## Preview controls
### use_directory_urls
This setting controls the style used for linking to pages within the
documentation.
The following table demonstrates how the URLs used on the site differ when
setting `use_directory_urls` to `true` or `false`.
Source file | Generated HTML | use_directory_urls=true | use_directory_urls=false
------------ | -------------------- | ------------------------ | ------------------------
index.md | index.html | / | /index.html
api-guide.md | api-guide/index.html | /api-guide/ | /api-guide/index.html
about.md | about/index.html | /about/ | /about/index.html
The default style of `use_directory_urls=true` creates more user friendly URLs,
and is usually what you'll want to use.
The alternate style can occasionally be useful if you want your documentation to
remain properly linked when opening pages directly from the file system, because
it create links that point directly to the target *file* rather than the target
*directory*.
**default**: `true`
### strict
Determines if a broken link to a page within the documentation is considered a
warning or an error (link to a page not listed in the pages setting). Set to
true to halt processing when a broken link is found, false prints a warning.
**default**: `false`
### dev_addr
Determines the address used when running `mkdocs serve`. Setting this allows you
to use another port, or allows you to make the service accessible over your
local network by using the `0.0.0.0` address.
As with all settings, you can set this from the command line, which can be
useful, for example:
```bash
mkdocs serve --dev-addr=0.0.0.0:80 # Run on port 80, on the local network.
```
**default**: `'127.0.0.1:8000'`
## Formatting options
### markdown_extensions
MkDocs uses the [Python Markdown][pymkd] library to translate Markdown files
into HTML. Python Markdown supports a variety of [extensions][pymdk-extensions]
that customize how pages are formatted. This setting lets you enable a list of
extensions beyond the ones that MkDocs uses by default (`meta`, `toc`, `tables`,
and `fenced_code`).
For example, to enable the [SmartyPants typography extension][smarty], use:
```yaml
markdown_extensions:
- smarty
```
Some extensions provide configuration options of their own. If you would like to
set any configuration options, then you can nest a key/value mapping
(`option_name: option value`) of any options that a given extension supports.
See the documentation for the extension you are using to determine what options
they support.
For example, to enable permalinks in the (included) `toc` extension, use:
```yaml
markdown_extensions:
- toc:
permalink: True
```
Note that a colon (`:`) must follow the extension name (`toc`) and then on a new
line the option name and value must be indented and seperated by a colon. If you
would like to define multipe options for a single extension, each option must be
defined on a seperate line:
```yaml
markdown_extensions:
- toc:
permalink: True
separator: "_"
```
Add an additional item to the list for each extension. If you have no
configuration options to set for a specific extension, then simply omit options
for that extension:
```yaml
markdown_extensions:
- smarty
- toc:
permalink: True
- sane_lists
```
!!! note "See Also:"
The Python-Markdown documentation provides a [list of extensions][exts]
which are available out-of-the-box. For a list of configuration options
available for a given extension, see the documentation for that extension.
You may also install and use various [third party extensions][3rd]. Consult
the documentation provided by those extensions for installation instructions
and available configuration options.
**default**: `[]`
[custom themes]: custom-themes.md
[variables that are available]: custom-themes.md#template-variables
[pymdk-extensions]: https://pythonhosted.org/Markdown/extensions/index.html
[pymkd]: https://pythonhosted.org/Markdown/
[smarty]: https://pythonhosted.org/Markdown/extensions/smarty.html
[exts]:https://pythonhosted.org/Markdown/extensions/index.html
[3rd]: https://github.com/waylan/Python-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
[extra_css]: #extra_css
# Custom themes
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.
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.
## Creating a custom theme
The bare minimum required for a custom theme is a `main.html` [Jinja2
template] file. This should be placed in a directory which will be the
`theme_dir` and it should be created next to the `mkdocs.yml` configuration
file. Within `mkdocs.yml`, specify the `theme_dir` option and set it to the
name of the directory containing `main.html`. For example, given this example
project layout:
mkdocs.yml
docs/
index.md
about.md
custom_theme/
main.html
...
You would include the following settings in `mkdocs.yml` to use the custom theme
directory:
theme: null
theme_dir: 'custom_theme'
!!! Note
Generally, when building your own custom theme, the `theme` configuration
setting would be set to `null`. However, if used in combination with the
`theme_dir` configuration value a custom theme can be used to replace only
specific parts of a built-in theme. For example, with the above layout and
if you set `theme: "mkdocs"` then the `main.html` file in the `theme_dir`
would replace that in the theme but otherwise the `mkdocs` theme would
remain the same. This is useful if you want to make small adjustments to an
existing theme.
For more specific information, see [styling your docs].
[styling your docs]: ./styling-your-docs.md#using-the-theme_dir
## Basic theme
The simplest `main.html` file is the following:
```django
<!DOCTYPE html>
<html>
<head>
<title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>
</head>
<body>
{{ content }}
</body>
</html>
```
Article content from each page specified in `mkdocs.yml` is inserted using the
`{{ content }}` tag. Style-sheets and scripts can be brought into this theme as
with a normal HTML file. Navbars and tables of contents can also be generated
and included automatically, through the `nav` and `toc` objects, respectively.
If you wish to write your own theme, it is recommended to start with one of
the [built-in themes] and modify it accordingly.
!!! Note
As MkDocs uses [Jinja] as its template engine, you have access to all the
power of Jinja, including [template inheritance]. You may notice that the
themes included with MkDocs make extensive use of template inheritance and
blocks, allowing users to easily override small bits and pieces of the
templates from the [theme_dir]. Therefore, the built-in themes are
implemented in a `base.html` file, which `main.html` extends. Although not
required, third party template authors are encouraged to follow a similar
pattern and may want to define the same [blocks] as are used in the built-in
themes for consistency.
[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
## Template Variables
Each template in a theme is built with a template context. These are the
variables that are available to themes. The context varies depending on the
template that is being built. At the moment templates are either built with
the global context or with a page specific context. The global context is used
for HTML pages that don't represent an individual Markdown document, for
example a 404.html page or search.html.
### Global Context
The following variables are available globally on any template.
#### config
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.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)
#### nav
The `nav` variable is used to create the navigation for the documentation.
Following is a basic usage example which outputs the first and second level
navigation as a nested list.
```django
{% if nav|length>1 %}
<ul>
{% for nav_item in nav %}
{% if nav_item.children %}
<li>{{ nav_item.title }}
<ul>
{% for nav_item in nav_item.children %}
<li class="{% if nav_item.active%}current{%endif%}">
<a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
</li>
{% endfor %}
</ul>
</li>
{% else %}
<li class="{% if nav_item.active%}current{%endif%}">
<a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
</li>
{% endif %}
{% endfor %}
</ul>
{% endif %}
```
The `nav` object also contains a `hompage` object, which points to the `page`
object of the homepage. For example, you may want to access `nav.homepage.url`.
#### base_url
The `base_url` provides a relative path to the root of the MkDocs project.
This makes it easy to include links to static assets in your theme. For
example, if your theme includes a `js` folder, to include `theme.js` from that
folder on all pages you would do this:
```django
<script src="{{ base_url }}/js/theme.js"></script>
```
#### extra_css
Contains a list of URLs to the style-sheets listed in the [extra_css]
config setting. Unlike the config setting, which contains local paths, this
variable contains absolute paths from the homepage.
[extra_css]: configuration.md#extra_css
#### extra_javascript
Contains a list of URLs to the scripts listed in the [extra_javascript] config
setting. Unlike the config setting, which contains local paths, this variable
contains absolute paths from the homepage.
[extra_javascript]: configuration.md#extra_javascript
#### mkdocs_version
Contains the current MkDocs version.
#### build_date_utc
A Python datetime object that represents the date and time the documentation
was built in UTC. This is useful for showing how recently the documentation
was updated.
#### page
In templates which are not rendered from a Markdown source file, the `page`
variable is `None`. In templates which are rendered from a Markdown source file,
the `page` variable contains a page object with the following attributes:
##### page.title
Contains the Title for the current page.
##### page.content
The rendered Markdown as HTML, this is the contents of the documentation.
##### page.toc
An object representing the Table of contents for a page. Displaying the table
of contents as a simple list can be achieved like this.
```django
<ul>
{% for toc_item in page.toc %}
<li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
{% for toc_item in toc_item.children %}
<li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
{% endfor %}
{% endfor %}
</ul>
```
##### page.meta
A mapping of the metadata included at the top of the markdown page. In this
example we define a `source` property above the page title.
```no-highlight
source: generics.py
mixins.py
# Page title
Content...
```
A template can access this metadata for the page with the `meta.source`
variable. This could then be used to link to source files related to the
documentation page.
```django
{% for filename in page.meta.source %}
<a class="github" href="https://github.com/.../{{ filename }}">
<span class="label label-info">{{ filename }}</span>
</a>
{% endfor %}
```
##### page.canonical_url
The full, canonical URL to the current page. This includes the `site_url` from
the configuration.
##### page.edit_url
The full URL to the input page in the source repository. Typically used to
provide a link to edit the source page.
##### page.url
The URL to the current page not including the `site_url` from the configuration.
##### page.is_homepage
Evaluates to `True` for the homepage of the site and `False` for all other
pages. This can be used in conjunction with other attributes of the `page`
object to alter the behavior. For example, to display a different title
on the homepage:
```django
{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}
```
##### page.previous_page
The page object for the previous page. The usage is the same as for
`page`.
##### page.next_page
The page object for the next page.The usage is the same as for `page`.
### Extra Context
Additional variables can be passed to the template with the
[`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
and a list of links related to the project. This can be achieved with the
following `extra` configuration:
```yaml
extra:
version: 0.13.0
links:
- https://github.com/mkdocs
- https://docs.readthedocs.org/en/latest/builds.html#mkdocs
- http://www.mkdocs.org/
```
And then displayed with this HTML in the custom theme.
```django
{{ config.extra.version }}
{% if config.extra.links %}
<ul>
{% for link in config.extra.links %}
<li>{{ link }}</li>
{% endfor %}
</ul>
{% endif %}
```
## Search and themes
As of MkDocs `0.13` client side search support has been added to MkDocs with
[Lunr.js].
Search can either be added to every page in the theme or to a dedicated
template which must be named `search.html`. The search template will be build
with the same name and can be viewable with `mkdocs serve` at
`http://localhost:8000/search.html`. An example of the two different
approaches can be seen by comparing the `mkdocs` and `readthedocs` themes.
The following HTML needs to be added to the theme so the JavaScript is loaded
for Lunr.js.
```django
<script>var base_url = '{{ base_url }}';</script>
<script data-main="{{ base_url }}/mkdocs/js/search.js" src="{{ base_url }}/mkdocs/js/require.js"></script>
```
!!! note
The above JavaScript will download the search index, for larger
documentation projects this can be a heavy operation. In those cases, it
is suggested that you either use the `search.html` approach to only
include search on one page or load the JavaScript on an event like a form
submit.
This loads the JavaScript and sets a global variable `base_url` which allows
the JavaScript to make the links relative to the current page. The above
JavaScript, with the following HTML in a `search.html` template will add a
full search implementation to your theme.
```django
<h1 id="search">Search Results</h1>
<form action="search.html">
<input name="q" id="mkdocs-search-query" type="text" >
</form>
<div id="mkdocs-search-results">
Sorry, page not found.
</div>
```
This works by looking for the specific ID's used in the above HTML. The input
for the user to type the search query must have the ID `mkdocs-search-query`
and `mkdocs-search-results` is the directory where the results will be placed.
[Jinja2 template]: http://jinja.pocoo.org/docs/dev/
[built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes
[lunr.js]: http://lunrjs.com/
## Packaging Themes
MkDocs makes use of [Python packaging] to distribute themes. This comes with a
few requirements.
To see an example of a package containing one theme, see the [MkDocs Bootstrap
theme] and to see a package that contains many themes, see the [MkDocs
Bootswatch theme].
!!! Note
It is not strictly necessary to package a theme, as the entire theme
can be contained in the `theme_dir`. If you have created a "one-off theme,"
that should be sufficent. However, if you intend to distribute your theme
for others to use, packaging the theme has some advantages. By packaging
your theme, your users can more easily install it and they can them take
advantage of the [theme_dir] to make tweaks to your theme to better suit
their needs.
[Python packaging]: https://packaging.python.org/en/latest/
[MkDocs Bootstrap theme]: http://mkdocs.github.io/mkdocs-bootstrap/
[MkDocs Bootswatch theme]: http://mkdocs.github.io/mkdocs-bootswatch/
### Package Layout
The following layout is recommended for themes. Two files at the top level
directory called `MANIFEST.in` amd `setup.py` beside the theme directory which
contains an empty `__init__.py` file and your template and media files.
```no-highlight
.
|-- MANIFEST.in
|-- theme_name
| |-- __init__.py
| |-- main.py
| |-- styles.css
`-- setup.py
```
The `MANIFEST.in` file should contain the following contents but with
theme_name updated and any extra file extensions added to the include.
```no-highlight
recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff
recursive-exclude * __pycache__
recursive-exclude * *.py[co]
```
The `setup.py` should include the following text with the modifications
described below.
```python
from setuptools import setup, find_packages
VERSION = '0.0.1'
setup(
name="mkdocs-themename",
version=VERSION,
url='',
license='',
description='',
author='',
author_email='',
packages=find_packages(),
include_package_data=True,
entry_points={
'mkdocs.themes': [
'themename = theme_name',
]
},
zip_safe=False
)
```
Fill in the URL, license, description, author and author email address.
The name should follow the convention `mkdocs-themename` (like `mkdocs-
bootstrap` and `mkdocs-bootswatch`), starting with MkDocs, using hyphens to
separate words and including the name of your theme.
Most of the rest of the file can be left unedited. The last section we need to
change is the entry_points. This is how MkDocs finds the theme(s) you are
including in the package. The name on the left is the one that users will use
in their mkdocs.yml and the one on the right is the directory containing your
theme files.
The directory you created at the start of this section with the main.html file
should contain all of the other theme files. The minimum requirement is that
it includes a `main.html` for the theme. It **must** also include a
`__init__.py` file which should be empty, this file tells Python that the
directory is a package.
### Distributing Themes
With the above changes, your theme should now be ready to install. This can be
done with pip, using `pip install .` if you are still in the same directory as
the setup.py.
Most Python packages, including MkDocs, are distributed on PyPI. To do this,
you should run the following command.
```no-highlight
python setup.py register
```
If you don't have an account setup, you should be prompted to create one.
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/
# 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. 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 gh-pages branch by hand if you're using
the `gh-deploy` command because you will lose your work.
[GitHub]: https://github.com/
[GitHub Pages]: https://pages.github.com/
[ghp-import]: https://github.com/davisp/ghp-import
## Read the Docs
[Read the Docs][rtd] offers free documentation hosting. You can import your docs
using any major version control system, including Mercurial, Git, Subversion,
and Bazaar. 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.
!!! note
To benefit from all of the [features] offered by Read the Docs, you will need
to use the [Read the Docs theme][theme] which ships with MkDocs. The various
themes which may be referenced in Read the Docs' documentation are Sphinx
specific themes and will not work with MkDocs.
[rtd]: https://readthedocs.org/
[instructions]: https://read-the-docs.readthedocs.io/en/latest/getting_started.html#in-markdown
[features]: http://read-the-docs.readthedocs.io/en/latest/features.html
[theme]: /user-guide/styling-your-docs.md
## PyPI
If you maintain a [Python] project which is hosted on the [Python Package
Index][PyPI] (PyPI), you can use the hosting provided at [pythonhosted.org] to
host documentation for your project. Run the following commands from your
project's root directory to upload your documentation:
```sh
mkdocs build
python setup.py upload_docs --upload-dir=site
```
Your documentation will be hosted at `https://pythonhosted.org/<projectname>/`
where `<projectname>` is the name you used to register your project with PyPI.
There are a few prerequisites for the above to work:
1. You must be using [Setuptools] in your `setup.py` script ([Distutils] does
not offer an `upload_docs` command).
1. Your project must already be registered with PyPI (use `python setup.py
register`).
1. Your `mkdocs.yml` config file and your "docs" directory (value assigned to
the [docs_dir] configuration option) are presumed to be in the root directory
of your project alongside your `setup.py` script.
1. It is assumed that the default value (`"site"`) is assigned to the [site_dir]
configuration option in your `mkdocs.yaml` config file. If you have set a
different value, assign that value to the `--upload-dir` option.
[Python]: http://www.python.org/
[PyPI]: https://pypi.python.org/pypi
[pythonhosted.org]: https://pythonhosted.org/
[Setuptools]: https://pythonhosted.org/setuptools/
[Distutils]: https://docs.python.org/2/distutils/
[docs_dir]: configuration.md#docs_dir
[site_dir]: configuration.md#site_dir
## 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".
## 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/#site_dir
# 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 directory][theme_dir]. You
can also create your own [custom theme] from the grown up for your
documentation.
To use a theme that is included in MkDocs, simply add this to your
`mkdocs.yml` config file.
theme: readthedocs
Replace [`readthedocs`](#readthedocs) with any of the [built-in themes] 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
![mkdocs](/img/mkdocs.png)
### readthedocs
![ReadTheDocs](http://docs.readthedocs.io/en/latest/_images/screen_mobile.png)
### 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_dir].
### 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_dir].
### Using the theme_dir
The [theme_dir] configuration option can be used to point to a directory of
files which override the files in the theme set on the [theme] configuration
option. Any file in the `theme_dir` with the same name as a file in the `theme`
will replace the file of the same name in the `theme`. Any additional files in
the `theme_dir` will be added to the `theme`. The contents of the `theme_dir`
should mirror the directory structure of the `theme`. You may include templates,
JavaScript files, CSS files, images, fonts, or any other media included in a
theme.
!!! Note
For this to work, the `theme` setting must be set to a known installed theme.
If the `theme` setting is instead set to `null` (or not defined), then there
is no theme to override and the contents of the `theme_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_dir: custom_theme
```
To override the 404 error page ("file not found"), add a new template file named
`404.html` to the `custom_theme` directory. For information on what can be
included in a template, review the documentation for building a [custom theme].
To override the favicon, you can add a new icon file at
`custom_theme/img/favicon.ico`.
To include a JavaScript library, copy the library to the `custom_theme/js/`
directory.
Your directory structure should now look like this:
```nohighlight
- docs/
- index.html
- custom_theme/
- img/
- favicon.ico
- js/
- somelib.js
- 404.html
- config.yml
```
!!! Note
Any files included in the `theme` but not included in the `theme_dir` will
still be utilized. The `theme_dir` will only override/replace files in the
`theme`. If you want to remove files, or build a theme from scratch, then
you should review the documentation for building a [custom theme].
#### 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 `theme_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 title %}
<title>Custom title goes here</title>
{% endblock %}
```
In the above example, the title block defined in your custom `main.html` file
will be used in place of the default title 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_box`: 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
explaination of blocks, consult the [Jinja documentation].
#### Combining the theme_dir and Template Blocks
Adding a JavaScript library to the `theme_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 `theme_dir`. The same would be required for
any additional CSS files included in the `theme_dir`.
[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
[built-in themes]: #built-in-themes
[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/#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
[theme]: ./configuration/#theme
[theme_dir]: ./configuration/#theme_dir
[third party themes]: #third-party-themes
[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
[base_url]: ./custom-themes.md#base_url
# Writing your docs
How to write and layout your markdown source files.
---
## Configure Pages and Navigation
The [pages configuration](/user-guide/configuration.md#pages) in your
`mkdocs.yml` defines which pages are built by MkDocs and how they appear in the
documentation navigation. If not provided, the pages configuration will be
automatically created by discovering all the Markdown files in the
[documentation directory](/user-guide/configuration.md#docs_dir). An
automatically created pages configuration will always be sorted
alphanumerically by file name. You will need to manually define your pages
configuration if you would like your pages sorted differantly.
A simple pages configuration looks like this:
```no-highlight
pages:
- 'index.md'
- 'about.md'
```
With this example we will build two pages at the top level and they will
automatically have their titles inferred from the filename. Assuming `docs_dir`
has the default value, `docs`, the source files for this documentation would be
`docs/index.md` and `docs/about.md`. To provide a custom name for these pages,
they can be added before the filename.
```no-highlight
pages:
- Home: 'index.md'
- About: 'about.md'
```
### Multilevel documentation
Subsections can be created by listing related pages together under a section
title. For example:
```no-highlight
pages:
- Home: 'index.md'
- User Guide:
- 'Writing your docs': 'user-guide/writing-your-docs.md'
- 'Styling your docs': 'user-guide/styling-your-docs.md'
- About:
- 'License': 'about/license.md'
- 'Release Notes': 'about/release-notes.md'
```
With the above configuration we have three top level sections: Home, User Guide
and About. Then under User Guide we have two pages, Writing your docs and
Styling your docs. Under the About section we also have two pages, License and
Release Notes.
## File layout
Your documentation source should be written as regular Markdown files, and
placed in a directory somewhere in your project. Normally this directory will be
named `docs` and will exist at the top level of your project, alongside the
`mkdocs.yml` configuration file.
The simplest project you can create will look something like this:
```no-highlight
mkdocs.yml
docs/
index.md
```
By convention your project homepage should always be named `index`. Any of the
following extensions may be used for your Markdown source files: `markdown`,
`mdown`, `mkdn`, `mkd`, `md`.
You can also create multi-page documentation, by creating several markdown
files:
```no-highlight
mkdocs.yml
docs/
index.md
about.md
license.md
```
The file layout you use determines the URLs that are used for the generated
pages. Given the above layout, pages would be generated for the following URLs:
```no-highlight
/
/about/
/license/
```
You can also include your Markdown files in nested directories if that better
suits your documentation layout.
```no-highlight
docs/
index.md
user-guide/getting-started.md
user-guide/configuration-options.md
license.md
```
Source files inside nested directories will cause pages to be generated with
nested URLs, like so:
```no-highlight
/
/user-guide/getting-started/
/user-guide/configuration-options/
/license/
```
## Linking documents
MkDocs allows you to interlink your documentation by using regular Markdown
hyperlinks.
### Internal hyperlinks
When linking between pages in the documentation you can simply use the regular
Markdown hyperlinking syntax, including the relative path to the Markdown
document you wish to link to.
Please see the [project license](license.md) for further details.
When the MkDocs build runs, these hyperlinks will automatically be transformed
into a hyperlink to the appropriate HTML page.
When working on your documentation you should be able to open the linked
Markdown document in a new editor window simply by clicking on the link.
If the target documentation file is in another directory you'll need to make
sure to include any relative directory path in the hyperlink.
Please see the [project license](../about/license.md) for further details.
You can also link to a section within a target documentation page by using an
anchor link. The generated HTML will correctly transform the path portion of the
hyperlink, and leave the anchor portion intact.
Please see the [project license](about.md#license) for further details.
## 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](https://help.github.com/articles/using-a-custom-domain-with-github-pages/)
and a PNG formatted screenshot image then your file layout might look as
follows:
```no-highlight
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.
![Screenshot](img/screenshot.png)
*Above: Cupcake indexer in progress*
```
You 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.
## Markdown extensions
MkDocs supports the following Markdown extensions.
### Tables
A simple table looks like this:
```no-highlight
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:
```no-highlight
| 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:
```no-highlight
First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left | Center | Right
Left | Center | Right
```
### Fenced code blocks
The first line should contain 3 or more backtick (`` ` ``) characters, and the
last line should contain the same number of backtick characters (`` ` ``):
~~~no-highlight
```
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:
~~~no-highlight
```python
def fn():
pass
```
~~~
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment