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

Use a new MkDocs site

Browse Source
This commit is contained in:
Achilleas Pipinellis
2017-02-28 17:15:29 +01:00
parent 4536498c46
commit 48f7b16f3d
22 changed files with 75 additions and 2569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.gitlab-ci.yml Normal file
View File

@@ -0,0 +1,17 @@
image: python:alpine
before_script:
- pip install mkdocs
# Add your custom theme if not inside a theme_dir
# (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
# - pip install mkdocs-material
pages:
script:
- mkdocs build
- mv site public
artifacts:
paths:
- public
only:
- master

53
README.md
View File

@@ -1,7 +1,13 @@
# Example [MkDocs](http://mkdocs.org/) website using GitLab Pages. ![Build Status](https://gitlab.com/pages/mkdocs/badges/master/build.svg)
---
Example [MkDocs] website using GitLab Pages.
Learn more about GitLab Pages at https://pages.gitlab.io and the official Learn more about GitLab Pages at https://pages.gitlab.io and the official
documentation http://doc.gitlab.com/ee/pages/README.html. documentation https://docs.gitlab.com/ce/user/project/pages/.
---
## GitLab CI ## GitLab CI
@@ -13,7 +19,8 @@ image: python:alpine
before_script: before_script:
- pip install mkdocs - pip install mkdocs
# add your custom theme (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) if not inside a theme_dir ## Add your custom theme if not inside a theme_dir
## (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
# - pip install mkdocs-material # - pip install mkdocs-material
pages: pages:
@@ -32,17 +39,13 @@ pages:
To work locally with this project, you'll have to follow the steps below: To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project 1. Fork, clone or download this project
1. [Install](http://www.mkdocs.org/#installation) MkDocs 1. [Install][] MkDocs
1. Preview your project: `mkdocs serve` 1. Preview your project: `mkdocs serve`,
your site can be accessed under `localhost:8000`
1. Add content 1. Add content
1. Generate the website: `mkdocs build` (optional) 1. Generate the website: `mkdocs build` (optional)
Read more at MkDocs's [documentation](http://www.mkdocs.org/). Read more at MkDocs [documentation][].
### 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 ## GitLab User or Group Pages
@@ -52,6 +55,32 @@ your `username` or `groupname`. This can be done by navigating to your
project's **Settings**. project's **Settings**.
You'll need to configure your site too: change this line 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"`. 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]. Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Troubleshooting
1. CSS is missing! That means two things:
Either that you have wrongly set up the CSS URL in your templates, or
your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
[ci]: https://about.gitlab.com/gitlab-ci/
[mkdocs]: http://www.mkdocs.org
[install]: http://www.mkdocs.org/#installation
[documentation]: http://www.mkdocs.org
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
---
Forked from https://gitlab.com/morph027/mkdocs

1
docs/CNAME
View File

@@ -1 +0,0 @@
www.mkdocs.org

69
docs/about/contributing.md
View File

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

37
docs/about/license.md
View File

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

542
docs/about/release-notes.md
View File

@@ -1,542 +0,0 @@
# Release Notes
---
## Upgrading
To upgrade MkDocs to the latest version, use pip:
pip install -U mkdocs
You can determine your currently installed version using `mkdocs --version`:
$ mkdocs --version
mkdocs, version 0.15.2
## Maintenance team
The current and past members of the MkDocs team.
* [@tomchristie](https://github.com/tomchristie/)
* [@d0ugal](https://github.com/d0ugal/)
* [@waylan](https://github.com/waylan/)
## Version 0.16.1 (2016-12-22)
* Ensure scrollspy behavior does not affect nav bar (#1094)
* Only "load" a theme when it is explicitly requested by the user (#1105)
## Version 0.16 (2016-11-04)
### Major Additions to Version 0.16.0
#### Template variables refactored. (#874)
##### Page Context
Page specific variable names in the template context have been refactored as
defined in [Custom Themes](../user-guide/custom-themes/#page). The
old variable names will issue a warning but continue to work for version 0.16,
but may be removed in a future version.
Any of the following old page variables should be updated to the new ones in
user created and third-party templates:
| Old Variable Name | New Variable Name |
| ----------------- | ------------------- |
| current_page | [page] |
| page_title | [page.title] |
| content | [page.content] |
| toc | [page.toc] |
| meta | [page.meta] |
| canonical_url | [page.canonical_url]|
| previous_page | [page.previous_page]|
| next_page | [page.next_page] |
[page]: ../user-guide/custom-themes/#page
[page.title]: ../user-guide/custom-themes/#pagetitle
[page.content]: ../user-guide/custom-themes/#pagecontent
[page.toc]: ../user-guide/custom-themes/#pagetoc
[page.meta]: ../user-guide/custom-themes/#pagemeta
[page.canonical_url]: ../user-guide/custom-themes/#pagecanonical_url
[page.previous_page]: ../user-guide/custom-themes/#pageprevious_page
[page.next_page]: ../user-guide/custom-themes/#pagenext_page
##### Global Context
Additionally, a number of global variables have been altered and/or deprecated
and user created and third-party templates should be updated as outlined below:
Previously, the global variable `include_nav` was altered programmatically based
on the number of pages in the nav. The variable will issue a warning but
continue to work for version 0.16, but may be removed in a future version. Use
`{% if nav|length>1 %}` instead.
Previously, the global variable `include_next_prev` was altered programmatically
based on the number of pages in the nav. The variable will issue a warning but
continue to work for version 0.16, but may be removed in a future version. Use
`{% if page.next_page or page.previous_page %}` instead.
Previously the global variable `page_description` was altered programmatically
based on whether the current page was the homepage. Now it simply maps to
`config['site_description']`. Use `{% if page.is_homepage %}` in the template to
conditionally change the description.
The global variable `homepage_url` maps directly to `nav.homepage.url` and is
being deprecated. The variable will issue a warning but continue to work for
version 0.16, but may be removed in a future version. Use `nav.homepage.url`
instead.
The global variable `favicon` maps to the configuration setting `site_favicon`.
Both the template variable and the configuration setting are being deprecated
and will issue a warning but continue to work for version 0.16, and may be
removed in a future version. Use `{{ base_url }}/img/favicon.ico` in your
template instead. Users can simply save a copy of their custom favicon icon to
`img/favicon.ico` in either their `docs_dir` or `theme_dir`.
A number of variables map directly to similarly named variables in the `config`.
Those variables are being deprecated and will issue a warning but continue to
work for version 0.16, but may be removed in a future version. Use
`config.var_name` instead, where `var_name` is the name of one of the
[configuration] variables.
[configuration]: /user-guide/configuration.md
Below is a summary of all of the changes made to the global context:
| Old Variable Name | New Variable Name or Expression |
| ----------------- | -------------------------------------- |
| current_page | page |
| include_nav | nav|length>1 |
| include_next_prev | (page.next_page or page.previous_page) |
| site_name | config.site_name |
| site_author | config.site_author |
| page_description | config.site_description |
| repo_url | config.repo_url |
| repo_name | config.repo_name |
| site_url | config.site_url |
| copyright | config.copyright |
| google_analytics | config.google_analytics |
| homepage_url | nav.homepage.url |
| favicon | {{ base_url }}/img/favicon.ico |
#### Increased Template Customization. (#607)
The built-in themes have been updated by having each of their many parts wrapped
in template blocks which allow each individual block to be easily overridden
using the `theme_dir` config setting. Without any new settings, you can use a
different analytics service, replace the default search function, or alter the
behavior of the navigation, among other things. See the relevant
[documentation][blocks] for more details.
To enable this feature, the primary entry point for page templates has been
changed from `base.html` to `main.html`. This allows `base.html` to continue to
exist while allowing users to override `main.html` and extend `base.html`. For
version 0.16, `base.html` will continue to work if no `main.html` template
exists, but it is deprecated and will raise a warning. In version 1.0, a build
will fail if no `main.html` template exists. Any custom and third party
templates should be updated accordingly.
The easiest way for a third party theme to be updated would be to simply add a
`main.html` file which only contains the following line:
```django
{% extends "base.html" %}
```
That way, the theme contains the `main.html` entry point, and also supports
overriding blocks in the same manner as the built-in themes. Third party themes
are encouraged to wrap the various pieces of their templates in blocks in order
to support such customization.
[blocks]: ../user-guide/styling-your-docs/#overriding-template-blocks
#### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986)
In previous versions of MkDocs, if the `extra_css` or `extra_javascript` config
settings were empty, MkDocs would scan the `docs_dir` and auto-populate each
setting with all of the CSS and JavaScript files found. This behavior is
deprecated and a warning will be issued. In the next release, the auto-populate
feature will stop working and any unlisted CSS and JavaScript files will not be
included in the HTML templates. In other words, they will still be copied to the
`site-dir`, but they will not have any effect on the theme if they are not
explicitly listed.
All CSS and javaScript files in the `docs_dir` should be explicitly listed in
the `extra_css` or `extra_javascript` config settings going forward.
#### Support for dirty builds. (#990)
For large sites the build time required to create the pages can become problematic,
thus a "dirty" build mode was created. This mode simply compares the modified time
of the generated HTML and source markdown. If the markdown has changed since the
HTML then the page is re-constructed. Otherwise, the page remains as is. This mode
may be invoked in both the `mkdocs serve` and `mkdocs build` commands:
```text
mkdocs serve --dirtyreload
```
```text
mkdocs build --dirty
```
It is important to note that this method for building the pages is for development
of content only, since the navigation and other links do not get updated on other
pages.
#### Stricter Directory Validation
Previously, a warning was issued if the `site_dir` was a child directory of the
`docs_dir`. This now raises an error. Additionally, an error is now raised if
the `docs_dir` is set to the directory which contains your config file rather
than a child directory. You will need to rearrange you directory structure to
better conform with the documented [layout].
[layout]: ../user-guide/writing-your-docs/#file-layout
### Other Changes and Additions to Version 0.16.0
* Bugfix: Support `gh-deploy` command on Windows with Python 3 (#722)
* Bugfix: Include .woff2 font files in Python package build (#894)
* Various updates and improvements to Documentation Home Page/Tutorial (#870)
* Bugfix: Support livereload for config file changes (#735)
* Bugfix: Non-media template files are no longer copied with media files (#807)
* Add a flag (-e/--theme-dir) to specify theme directory with the commands
`mkdocs build` and `mkdocs serve` (#832)
* Fixed issues with Unicode file names under Windows and Python 2. (#833)
* Improved the styling of in-line code in the MkDocs theme. (#718)
* Bugfix: convert variables to JSON when being passed to JavaScript (#850)
* Updated the ReadTheDocs theme to match the upstream font sizes and colors
more closely. (#857)
* Fixes an issue with permalink markers showing when the mouse was far above
them (#843)
* Bugfix: Handle periods in directory name when automatically creating the
pages config. (#728)
* Update searching to Lunr 0.7, which comes with some performance enhancements
for larger documents (#859)
* Bugfix: Support SOURCE_DATE_EPOCH environment variable for "reproducible"
builds (#938)
* Follow links when copying media files (#869).
* Change "Edit on..." links to point directly to the file in the source
repository, rather than to the root of the repository (#975), configurable
via the new [`edit_uri`](../user-guide/configuration.md#edit_uri) setting.
* Bugfix: Don't override config value for strict mode if not specified on CLI
(#738).
* Add a `--force` flag to the `gh-deploy` command to force the push to the
repository (#973).
* Improve alignment for current selected menu item in readthedocs theme (#888).
* `http://user.github.io/repo` => `https://user.github.io/repo/` (#1029).
* Improve installation instructions (#1028).
* Account for wide tables and consistently wrap inline code spans (#834).
* Bugfix: Use absolute URLs in nav & media links from error templates (#77).
## Version 0.15.3 (2016-02-18)
* Improve the error message the given theme can't be found.
* Fix an issue with relative symlinks (#639)
## Version 0.15.2 (2016-02-08)
* Fix an incorrect warning that states external themes [will be removed from
MkDocs](#add-support-for-installable-themes).
## Version 0.15.1 (2016-01-30)
* Lower the minimum supported Click version to 3.3 for package maintainers.
(#763)
## Version 0.15.0 (2016-01-21)
### Major Additions to Version 0.15.0
#### Add support for installable themes
MkDocs now supports themes that are distributed via Python packages. With this
addition, the Bootstrap and Bootswatch themes have been moved to external git
repositories and python packages. See their individual documentation for more
details about these specific themes.
* [MkDocs Bootstrap]
* [MkDocs Bootswatch]
[MkDocs Bootstrap]: http://mkdocs.github.io/mkdocs-bootstrap/
[MkDocs Bootswatch]: http://mkdocs.github.io/mkdocs-bootswatch/
They will be included with MkDocs by default until a future release. After that
they will be installable with pip: `pip install mkdocs-bootstrap` and `pip
install mkdocs-bootswatch`
See the documentation for [Styling your docs] for more information about using
and customising themes and [Custom themes] for creating and distributing new
themes
[Styling your docs]: /user-guide/styling-your-docs.md
[Custom themes]: /user-guide/custom-themes.md
### Other Changes and Additions to Version 0.15.0
* Fix issues when using absolute links to Markdown files. (#628)
* Deprecate support of Python 2.6, pending removal in 1.0.0. (#165)
* Add official support for Python version 3.5.
* Add support for [site_description] and [site_author] to the [ReadTheDocs]
theme. (#631)
* Update FontAwesome to 4.5.0. (#789)
* Increase IE support with X-UA-Compatible. (#785)
* Added support for Python's `-m` flag. (#706)
* Bugfix: Ensure consistent ordering of auto-populated pages. (#638)
* Bugfix: Scroll the tables of contents on the MkDocs theme if it is too long
for the page. (#204)
* Bugfix: Add all ancestors to the page attribute `ancestors` rather than just
the initial one. (#693)
* Bugfix: Include HTML in the build output again. (#691)
* Bugfix: Provide filename to Read the Docs. (#721 and RTD#1480)
* Bugfix: Silence Click's unicode_literals warning. (#708)
[site_description]: /user-guide/configuration.md#site_description
[site_author]: /user-guide/configuration.md#site_author
[ReadTheDocs]: /user-guide/styling-your-docs.md#readthedocs
## Version 0.14.0 (2015-06-09)
* Improve Unicode handling by ensuring that all config strings are loaded as
Unicode. (#592)
* Remove dependancy on the six library. (#583)
* Remove dependancy on the ghp-import library. (#547)
* Add `--quiet` and `--verbose` options to all subcommands. (#579)
* Add short options (`-a`) to most command line options. (#579)
* Add copyright footer for readthedocs theme. (#568)
* If the requested port in `mkdocs serve` is already in use, don't show the
user a full stack trace. (#596)
* Bugfix: Fix a JavaScript encoding problem when searching with spaces. (#586)
* Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root.
(#578)
* Bugfix: Handle (pass-through instead of dropping) HTML entities while
parsing TOC. (#612)
* Bugfix: Default extra_templates to an empty list, don't automatically
discover them. (#616)
## Version 0.13.3 (2015-06-02)
* Bugfix: Reduce validation error to a warning if the site_dir is within
the docs_dir as this shouldn't cause any problems with building but will
inconvenience users building multiple times. (#580)
## Version 0.13.2 (2015-05-30)
* Bugfix: Ensure all errors and warnings are logged before exiting. (#536)
* Bugfix: Fix compatibility issues with ReadTheDocs. (#554)
## Version 0.13.1 (2015-05-27)
* Bugfix: Fix a problem with minimal configurations which only contain a list
of paths in the pages config. (#562)
## Version 0.13.0 (2015-05-26)
### Deprecations to Version 0.13.0
#### Deprecate the JSON command
In this release the `mkdocs json` command has been marked as deprecated and
when used a deprecation warning will be shown. It will be removed in a [future
release] of MkDocs, version 1.0 at the latest. The `mkdocs json` command
provided a convenient way for users to output the documentation contents as
JSON files but with the additions of search to MkDocs this functionality is
duplicated.
A new index with all the contents from a MkDocs build is created in the
[site_dir], so with the default value for the `site_dir` It can be found in
`site/mkdocs/search_index.json`.
This new file is created on every MkDocs build (with `mkdocs build`) and
no configuration is needed to enable it.
[future release]: https://github.com/mkdocs/mkdocs/pull/481
[site_dir]: /user-guide/configuration.md#site_dir
#### Change the pages configuration
Provide a [new way] to define pages, and specifically [nested pages], in the
mkdocs.yml file and deprecate the existing approach, support will be removed
with MkDocs 1.0.
[new way]: /user-guide/writing-your-docs.md#configure-pages-and-navigation
[nested pages]: /user-guide/writing-your-docs.md#multilevel-documentation
#### Warn users about the removal of builtin themes
All themes other than mkdocs and readthedocs will be moved into external
packages in a future release of MkDocs. This will enable them to be more easily
supported and updates outside MkDocs releases.
### Major Additions to Version 0.13.0
#### Search
Support for search has now been added to MkDocs. This is based on the
JavaScript library [lunr.js]. It has been added to both the `mkdocs` and
`readthedocs` themes. See the custom theme documentation on [supporting search]
for adding it to your own themes.
[lunr.js]: http://lunrjs.com/
[supporting search]: /user-guide/styling-your-docs.md#search-and-themes
#### New Command Line Interface
The command line interface for MkDocs has been re-written with the Python
library [Click]. This means that MkDocs now has an easier to use interface
with better help output.
This change is partially backwards incompatible as while undocumented it was
possible to pass any configuration option to the different commands. Now only
a small subset of the configuration options can be passed to the commands. To
see in full commands and available arguments use `mkdocs --help` and
`mkdocs build --help` to have them displayed.
[Click]: http://click.pocoo.org/4/
#### Support Extra HTML and XML files
Like the [extra_javascript] and [extra_css] configuration options, a new
option named [extra_templates] has been added. This will automatically be
populated with any `.html` or `.xml` files in the project docs directory.
Users can place static HTML and XML files and they will be copied over, or they
can also use Jinja2 syntax and take advantage of the [global variables].
By default MkDocs will use this approach to create a sitemap for the
documentation.
[extra_javascript]: /user-guide/configuration.md#extra_javascript
[extra_css]: /user-guide/configuration.md#extra_css
[extra_templates]: /user-guide/configuration.md#extra_templates
[global variables]: /user-guide/styling-your-docs.md#global-context
### Other Changes and Additions to Version 0.13.0
* Add support for [Markdown extension configuration options]. (#435)
* MkDocs now ships Python [wheels]. (#486)
* Only include the build date and MkDocs version on the homepage. (#490)
* Generate sitemaps for documentation builds. (#436)
* Add a clearer way to define nested pages in the configuration. (#482)
* Add an [extra config] option for passing arbitrary variables to the template. (#510)
* Add `--no-livereload` to `mkdocs serve` for a simpler development server. (#511)
* Add copyright display support to all themes (#549)
* Add support for custom commit messages in a `mkdocs gh-deploy` (#516)
* Bugfix: Fix linking to media within the same directory as a markdown file
called index.md (#535)
* Bugfix: Fix errors with unicode filenames (#542).
[extra config]: /user-guide/configuration.md#extra
[Markdown extension configuration options]: /user-guide/configuration.md#markdown_extensions
[wheels]: http://pythonwheels.com/
## Version 0.12.2 (2015-04-22)
* Bugfix: Fix a regression where there would be an error if some child titles
were missing but others were provided in the pages config. (#464)
## Version 0.12.1 (2015-04-14)
* Bugfix: Fixed a CSS bug in the table of contents on some browsers where the
bottom item was not clickable.
## Version 0.12.0 (2015-04-14)
* Display the current MkDocs version in the CLI output. (#258)
* Check for CNAME file when using gh-deploy. (#285)
* Add the homepage back to the navigation on all themes. (#271)
* Add a strict more for local link checking. (#279)
* Add Google analytics support to all themes. (#333)
* Add build date and MkDocs version to the ReadTheDocs and MkDocs theme
outputs. (#382)
* Standardise highlighting across all themes and add missing languages. (#387)
* Add a verbose flag. (-v) to show more details about what the build. (#147)
* Add the option to specify a remote branch when deploying to GitHub. This
enables deploying to GitHub pages on personal and repo sites. (#354)
* Add favicon support to the ReadTheDocs theme HTML. (#422)
* Automatically refresh the browser when files are edited. (#163)
* Bugfix: Never re-write URL's in code blocks. (#240)
* Bugfix: Don't copy ditfiles when copying media from the `docs_dir`. (#254)
* Bugfix: Fix the rendering of tables in the ReadTheDocs theme. (#106)
* Bugfix: Add padding to the bottom of all bootstrap themes. (#255)
* Bugfix: Fix issues with nested Markdown pages and the automatic pages
configuration. (#276)
* Bugfix: Fix a URL parsing error with GitHub enterprise. (#284)
* Bugfix: Don't error if the mkdocs.yml is completely empty. (#288)
* Bugfix: Fix a number of problems with relative urls and Markdown files. (#292)
* Bugfix: Don't stop the build if a page can't be found, continue with other
pages. (#150)
* Bugfix: Remove the site_name from the page title, this needs to be added
manually. (#299)
* Bugfix: Fix an issue with table of contents cutting off Markdown. (#294)
* Bugfix: Fix hostname for BitBucket. (#339)
* Bugfix: Ensure all links end with a slash. (#344)
* Bugfix: Fix repo links in the readthedocs theme. (#365)
* Bugfix: Include jQuery locally to avoid problems using MkDocs offline. (#143)
* Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (#384)
* Bugfix: Remove inline CSS in the ReadTheDocs theme. (#393)
* Bugfix: Fix problems with the child titles due to the order the pages config
was processed. (#395)
* Bugfix: Don't error during live reload when the theme doesn't exist. (#373)
* Bugfix: Fix problems with the Meta extension when it may not exist. (#398)
* Bugfix: Wrap long inline code otherwise they will run off the screen. (#313)
* Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to
fix problems with titles containing code. (#367)
* Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden
under the navigation. (#7)
* Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (#295)
* Bugfix: Fix an error when passing in a specific config file with
`mkdocs serve`. (#341)
* Bugfix: Don't overwrite index.md diles with the `mkdocs new` command. (#412)
* Bugfix: Remove bold and italic from code in the ReadTheDocs theme. (#411)
* Bugfix: Display images inline in the MkDocs theme. (#415)
* Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. (#319)
* Bugfix: Don't delete hidden files when using `mkdocs build --clean`. (#346)
* Bugfix: Don't block newer verions of Python-markdown on Python >= 2.7. (#376)
* Bugfix: Fix encoding issues when opening files across platforms. (#428)
## Version 0.11.1 (2014-11-20)
* Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs
theme. (#233)
## Version 0.11.0 (2014-11-18)
* Render 404.html files if they exist for the current theme. (#194)
* Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs
and ReadTheDocs themes. (#225)
* Bugfix: Fix an issue with the google_analytics code. (#219)
* Bugfix: Remove `__pycache__` from the package tar. (#196)
* Bugfix: Fix markdown links that go to an anchor on the current page. (#197)
* Bugfix: Don't add `prettyprint well` CSS classes to all HTML, only add it in
the MkDocs theme. (#183)
* Bugfix: Display section titles in the ReadTheDocs theme. (#175)
* Bugfix: Use the polling observer in watchdog so rebuilding works on
filesystems without inotify. (#184)
* Bugfix: Improve error output for common configuration related errors. (#176)
## Version 0.10.0 (2014-10-29)
* Added support for Python 3.3 and 3.4. (#103)
* Configurable Python-Markdown extensions with the config setting
`markdown_extensions`. (#74)
* Added `mkdocs json` command to output your rendered
documentation as json files. (#128)
* Added `--clean` switch to `build`, `json` and `gh-deploy` commands to
remove stale files from the output directory. (#157)
* Support multiple theme directories to allow replacement of
individual templates rather than copying the full theme. (#129)
* Bugfix: Fix `<ul>` rendering in readthedocs theme. (#171)
* Bugfix: Improve the readthedocs theme on smaller displays. (#168)
* Bugfix: Relaxed required python package versions to avoid clashes. (#104)
* Bugfix: Fix issue rendering the table of contents with some configs. (#146)
* Bugfix: Fix path for embedded images in sub pages. (#138)
* Bugfix: Fix `use_directory_urls` config behaviour. (#63)
* Bugfix: Support `extra_javascript` and `extra_css` in all themes. (#90)
* Bugfix: Fix path-handling under Windows. (#121)
* Bugfix: Fix the menu generation in the readthedocs theme. (#110)
* Bugfix: Fix the mkdocs command creation under Windows. (#122)
* Bugfix: Correctly handle external `extra_javascript` and `extra_css`. (#92)
* Bugfix: Fixed favicon support. (#87)

21
docs/css/extra.css
View File

@@ -1,21 +0,0 @@
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;
}

BIN
docs/img/initial-layout.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/img/mkdocs.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 158 KiB

BIN
docs/img/multipage.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/img/readthedocs.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 69 KiB

BIN
docs/img/screenshot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 78 KiB

BIN
docs/img/search.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 100 KiB

BIN
docs/img/site-name.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/img/win-py-install.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

361
docs/index.md
View File

@@ -1,352 +1,21 @@
# MkDocs # Welcome to MkDocs
Project documentation with&nbsp;Markdown. This is a test site hosted on [GitLab Pages](https://pages.gitlab.io). You can
[browse its source code](https://gitlab.com/pages/mkdocs), fork it and start
using it on your projects.
--- For full documentation visit [mkdocs.org](http://mkdocs.org).
!!! Note ## Commands
This site was built with GitLab Pages!.
Visit this project at [https://gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs). * `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs help` - Print this help message.
## Overview ## Project layout
MkDocs is a **fast**, **simple** and **downright gorgeous** static site mkdocs.yml # The configuration file.
generator that's geared towards building project documentation. Documentation docs/
source files are written in Markdown, and configured with a single YAML index.md # The documentation homepage.
configuration file. ... # Other markdown pages, images and other files.
### 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

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

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

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

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

@@ -1,266 +0,0 @@
# Styling your docs
How to style and theme your documentation.
---
MkDocs includes a couple [built-in themes] as well as various [third party
themes], all of which can easily be customized with [extra CSS or
JavaScript][docs_dir] or overridden from the [theme 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
View File

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

30
mkdocs.yml
View File

@@ -1,29 +1 @@
site_name: MkDocs site_name: My Docs by GitLab Pages
site_url: https://pages.gitlab.io/mkdocs
site_description: Project documentation with Markdown.
site_author: MkDocs Team
repo_url: https://gitlab.com/pages/mkdocs
pages:
- Home: index.md
- User Guide:
- Writing Your Docs: user-guide/writing-your-docs.md
- Styling Your Docs: user-guide/styling-your-docs.md
- Configuration: user-guide/configuration.md
- Deploying Your Docs: user-guide/deploying-your-docs.md
- Custom Themes: user-guide/custom-themes.md
- About:
- Release Notes: about/release-notes.md
- Contributing: about/contributing.md
- License: about/license.md
extra_css:
- css/extra.css
markdown_extensions:
- toc:
permalink:
- admonition:
copyright: Copyright &copy; 2014 <a href="/release-notes/">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.