MEDLab/democratic-mediums
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
morph027
2017-01-17 12:06:01 +01:00
commit 4536498c46
21 changed files with 2619 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
docs/user-guide/configuration.md Normal file
View File

@@ -0,0 +1,380 @@
# 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

483
docs/user-guide/custom-themes.md Normal file
View File

@@ -0,0 +1,483 @@
# 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/

140
docs/user-guide/deploying-your-docs.md Normal file
View File

@@ -0,0 +1,140 @@
# 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

266
docs/user-guide/styling-your-docs.md Normal file
View File

@@ -0,0 +1,266 @@
# 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

242
docs/user-guide/writing-your-docs.md Normal file
View File

@@ -0,0 +1,242 @@
# 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
```
~~~