diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 00000000..e69de29b
diff --git a/__init__.py b/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/about/contributing/index.html b/about/contributing/index.html
index 1b772ade..c205f7f7 100644
--- a/about/contributing/index.html
+++ b/about/contributing/index.html
@@ -207,26 +207,26 @@ traceback.
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.
+that you do this within a virtualenv.
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.
+this within a virtualenv.
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 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.
+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
diff --git a/about/release-notes/index.html b/about/release-notes/index.html
index 49308366..0fc7fdde 100644
--- a/about/release-notes/index.html
+++ b/about/release-notes/index.html
@@ -174,6 +174,10 @@
Upgrading
+ Version 0.14.0 (2015-06-09)
+
+ Version 0.13.3 (2015-06-02)
+
Version 0.13.2 (2015-05-30)
Version 0.13.1 (2015-05-27)
@@ -205,8 +209,33 @@
You can determine your currently installed version using mkdocs --version:
$ mkdocs --version
-mkdocs, version 0.13.0
+mkdocs, version 0.14.0
+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)
@@ -215,7 +244,7 @@ mkdocs, version 0.13.0
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)
+ of paths in the pages config. (#562)
Version 0.13.0 (2015-05-26)
Deprecations
diff --git a/fonts/fontawesome-webfont.eot b/fonts/fontawesome-webfont.eot
old mode 100644
new mode 100755
diff --git a/fonts/fontawesome-webfont.svg b/fonts/fontawesome-webfont.svg
old mode 100644
new mode 100755
diff --git a/fonts/fontawesome-webfont.ttf b/fonts/fontawesome-webfont.ttf
old mode 100644
new mode 100755
diff --git a/fonts/fontawesome-webfont.woff b/fonts/fontawesome-webfont.woff
old mode 100644
new mode 100755
diff --git a/index.html b/index.html
index 1c37857a..8bf18b0e 100644
--- a/index.html
+++ b/index.html
@@ -234,20 +234,20 @@ mkdocs [help|new|build|serve|gh-deploy] {options}
$ cd my-project
Let's take a moment to review the initial project that's been created for us.
-
+
There's a single configuration file named mkdocs.yml, and a folder named docs that will contain our documentation source files. Right now the docs folder just contains a single documentation page, named index.md.
MkDocs comes with a built-in webserver that lets you preview your documentation as you work on it. We start the webserver by making sure we're in the same directory as the mkdocs.yml config file, and then running the mkdocs serve command:
$ mkdocs serve
Running at: http://127.0.0.1:8000/
Open up http://127.0.0.1:8000/ in your browser, and you'll see the index page being displayed:
-
+
The webserver also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory or theme directory changes.
Go ahead and edit the docs/index.md file now and save the file. Then simply hit reload in the browser and you'll see your updated documentation.
Now's also a good time to edit the configuration file, mkdocs.yml. Change the site_name setting to something else and save the file.
-
+
Once you hit reload in the browser you'll see your new site name take effect.
-
+
Adding pages
Go ahead and edit the doc/index.md document, and change the initial heading to MkLorum, then reload the site in your browser, and you should see the change take effect immediately.
Let's also add a second page to our documentation:
@@ -269,7 +269,7 @@ pages:
theme: readthedocs
Refresh the browser again, and you'll now see the ReadTheDocs theme being used.
-
+
Building the site
That's looking good. We're ready to deploy the first pass of our MkLorum documentation now. Let's build the documentation.
$ mkdocs build
@@ -291,7 +291,7 @@ about css fonts img index.html js
able to host it from pretty much anywhere. GitHub project pages and Amazon
S3 are good hosting options. Upload the contents of the entire site directory
to wherever you're hosting your website from and you're done. For specific instructions
-for a number of common hosts, see the Deploying your Docs page.
+for a number of common hosts, see the Deploying your Docs page.
Getting help
To get help with MkDocs, please use the discussion group, GitHub issues or the MkDocs IRC channel #mkdocs on freenode.
@@ -341,6 +341,6 @@ for a number of common hosts, see the
http://www.mkdocs.org/
- 2015-05-31
+ 2015-06-09
daily
@@ -13,25 +13,25 @@
http://www.mkdocs.org/user-guide/configuration/
- 2015-05-31
+ 2015-06-09
daily
http://www.mkdocs.org/user-guide/deploying-your-docs/
- 2015-05-31
+ 2015-06-09
daily
http://www.mkdocs.org/user-guide/styling-your-docs/
- 2015-05-31
+ 2015-06-09
daily
http://www.mkdocs.org/user-guide/writing-your-docs/
- 2015-05-31
+ 2015-06-09
daily
@@ -41,19 +41,19 @@
http://www.mkdocs.org/about/contributing/
- 2015-05-31
+ 2015-06-09
daily
http://www.mkdocs.org/about/license/
- 2015-05-31
+ 2015-06-09
daily
http://www.mkdocs.org/about/release-notes/
- 2015-05-31
+ 2015-06-09
daily
diff --git a/user-guide/configuration/index.html b/user-guide/configuration/index.html
index 3c32f845..75f33158 100644
--- a/user-guide/configuration/index.html
+++ b/user-guide/configuration/index.html
@@ -234,30 +234,20 @@
default: null
remote_branch
-Set the remote branch to commit to when using gh-deploy to update Github Pages. This option can be overriden by a commandline option in gh-deploy.
+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: gh-pages
Documentation layout
pages
-This is setting is used to determine the set of pages that should be built for the documentation.
-The setting should be a list. Each row in the list represents information about a single page as a list of strings. The first string represents the path of the documentation source file, and should be relative to the docs_dir setting. Remaining strings represent the title of the page in the site navigation.
-Here's a simple example that would cause the build stage to create three 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.
pages:
- 'Introduction': 'index.md'
- 'User Guide': 'user-guide.md'
-- 'Abut': 'about.md'
+- 'About': 'about.md'
-Assuming the docs_dir setting was left with the default value of docs, the source files for this site's build process would be docs/index.md, docs/user-guide.md and docs/about.md.
-If you have a lot of project documentation you might choose to use headings to break up your site navigation by category. You can do so by including an extra string in the page configuration for any pages that require a navigation heading, like so:
-pages:
-- Introduction: 'index.md'
-- User Guide:
- - 'Creating a new Marshmallow project': 'user-guide/creating.md'
- - 'Marshmallow API guide': 'user-guide/api.md'
- - 'Configuring Marshmallow': 'user-guide/configuration.md'
-- About:
- - License: 'about/license.md'
-
-See also the section on configuring pages and navigation for a more detailed breakdown.
+See the section on configuring pages and navigation for a more detailed breakdown, including how to create sub-sections.
Build directories
theme
Sets the theme of your documentation site, for a list of available themes visit
@@ -290,6 +280,9 @@ documentation on how to ignore specific directories.
Set a list of JavaScript files to be included by the theme.
default: By default extra_javascript will contain a list of all the JavaScript files found within the docs_dir, if none are found it will be [] (an empty list).
+
+Set a list of templates 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.
+default: Unlike extra_css and extra_javascript, by default extra_templates will be [] (an empty list).
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.
default: By default extra will be an empty key value mapping.
diff --git a/user-guide/deploying-your-docs/index.html b/user-guide/deploying-your-docs/index.html
index 60d10cb6..67007a91 100644
--- a/user-guide/deploying-your-docs/index.html
+++ b/user-guide/deploying-your-docs/index.html
@@ -221,7 +221,7 @@ 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 which ships with MkDocs. The various
+to use the Read the Docs 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.
@@ -231,7 +231,7 @@ Index (PyPI), you can use the hosting provided at mkdocs build --clean
-python setup.py upload_docs --upload-dir=site
+python setup.py upload_docs --upload-dir=site
You documentation will be hosted at http://pythonhosted.org/<projectname>/
@@ -269,7 +269,7 @@ scp -r ./site usr@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.
+your hosts' file system.
See your host's documentation for specifics. You will likely want to search
their documentation for "ftp" or "uploading site".
diff --git a/user-guide/styling-your-docs/index.html b/user-guide/styling-your-docs/index.html
index fb96f824..158121ad 100644
--- a/user-guide/styling-your-docs/index.html
+++ b/user-guide/styling-your-docs/index.html
@@ -392,7 +392,23 @@ custom_theme/
-A mapping of the metadata included at the top of the markdown page.
+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.
+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.
+{% for filename in meta.source %}
+ <a class="github" href="https://github.com/.../{{ filename }}">
+ <span class="label label-info">{{ filename }}</span>
+ </a>
+{% endfor %}
+
+
canonical_url
The full, canonical URL to the current page. This includes the site_url from the configuration.
current_page
diff --git a/user-guide/writing-your-docs/index.html b/user-guide/writing-your-docs/index.html
index 34ff313b..59782c42 100644
--- a/user-guide/writing-your-docs/index.html
+++ b/user-guide/writing-your-docs/index.html
@@ -197,13 +197,13 @@
- '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. To provide a custom name for these pages, they can be added before the filename.
+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.
pages:
- Home: 'index.md'
- About: 'about.md'
Multilevel documentation
-To create a second level in the navigation and group topics, the category can be provided before the page title. This is best demonstrated in a documentation project with more pages and is slightly more complicated.
+Subsections can be created by listing related pages together under a section title. For example:
pages:
- Home: 'index.md'
- User Guide:
@@ -213,7 +213,7 @@
- '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
+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.
Note: At present MkDocs only supports a second level of navigation.
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.
@@ -263,18 +263,6 @@ Given the above layout, pages would be generated for the following URLs:
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.
-
-
As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media.
For example, if your project documentation needed to include a GitHub pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows:
@@ -297,22 +285,6 @@ docs/
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:
First Header | Second Header | Third Header