From 44fc6d92302651016869a11cc04a5281f742abae Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Fri, 26 Jun 2015 23:58:21 +0100 Subject: [PATCH] Added docuementation for packaging themes --- docs/css/extra.css | 4 + docs/index.md | 77 +++-- docs/user-guide/custom-themes.md | 417 +++++++++++++++++++++++++++ docs/user-guide/styling-your-docs.md | 291 ++++--------------- docs/user-guide/writing-your-docs.md | 140 +++++---- mkdocs.yml | 3 +- 6 files changed, 610 insertions(+), 322 deletions(-) create mode 100644 docs/user-guide/custom-themes.md diff --git a/docs/css/extra.css b/docs/css/extra.css index c1b6d587a1..5602f86b85 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -15,3 +15,7 @@ div.col-md-9 p.admonition-title:first-of-type { div.col-md-9 h1:first-of-type .headerlink { display: none; } + +code.no-highlight { + color: black; +} diff --git a/docs/index.md b/docs/index.md index 9d4b2e38f3..0573328c90 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,10 +38,12 @@ Get your project documentation looking just the way you want it by customizing t In order to 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 like so: - $ python --version - Python 2.7.2 - $ pip --version - pip 1.5.2 +```bash +$ python --version +Python 2.7.2 +$ pip --version +pip 1.5.2 +``` MkDocs supports Python 2.6, 2.7, 3.3 and 3.4. @@ -49,12 +51,16 @@ On Windows we recommend that you install Python and pip with [Chocolatey]. Install the `mkdocs` package using pip: - $ pip install mkdocs +```bash +$ pip install mkdocs +``` You should now have the `mkdocs` command installed on your system. Run `mkdocs --version` to check that everything worked okay. - $ mkdocs --version - mkdocs, version 0.14.0 +```bash +$ mkdocs --version +mkdocs, version 0.14.0 +``` --- @@ -63,8 +69,10 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs Getting started is super easy. - $ mkdocs new my-project - $ cd my-project +```bash +$ mkdocs new my-project +$ cd my-project +``` Let's take a moment to review the initial project that's been created for us. @@ -74,8 +82,10 @@ There's a single configuration file named `mkdocs.yml`, and a folder named `docs 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/ +```bash +$ mkdocs serve +Running at: http://127.0.0.1:8000/ +``` Open up [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your browser, and you'll see the index page being displayed: @@ -99,14 +109,18 @@ Go ahead and edit the `doc/index.md` document, and change the initial heading to Let's also add a second page to our documentation: - $ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md +```bash +$ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md +``` We'd like our documentation site to include some navigation headers, so we'll edit the configuration file and add some information about the order and title to use for out headers: - site_name: MkLorum - pages: - - Home: index.md - - About: about.md +```no-highlight +site_name: MkLorum +pages: +- Home: index.md +- About: about.md +``` Refresh the browser and you'll now see a navigation bar with `Home` and `About` headers. @@ -114,12 +128,13 @@ Refresh the browser and you'll now see a navigation bar with `Home` and `About` While we're here can also change the configuration file to alter how the documentation is displayed. Let's go ahead and change the theme. Edit the `mkdocs.yml` file to the following: - site_name: MkLorum - pages: - - Home: index.md - - About: about.md - theme: readthedocs - +```no-highlight +site_name: MkLorum +pages: +- Home: index.md +- About: about.md +theme: readthedocs +``` Refresh the browser again, and you'll now see the ReadTheDocs theme being used. @@ -129,24 +144,32 @@ Refresh the browser again, and you'll now see the ReadTheDocs theme being used. That's looking good. We're ready to deploy the first pass of our `MkLorum` documentation now. Let's build the documentation. - $ mkdocs build +```bash +$ mkdocs build +``` This will create a new directory, named `site`. Let's take a look inside the directory: - $ ls site - about css fonts img index.html js +```bash +$ ls site +about css fonts img index.html js +``` Notice that our source documentation has been output as two HTML files named `index.html` and `about/index.html`. We also have various other media that's been copied into the `site` directory as part of the documentation theme. 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. - $ echo "site/" >> .gitignore +```bash +$ echo "site/" >> .gitignore +``` If you're using another source code control 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. - $ mkdocs build --clean +```bash +$ mkdocs build --clean +``` ## Deploying diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md new file mode 100644 index 0000000000..578d9c458f --- /dev/null +++ b/docs/user-guide/custom-themes.md @@ -0,0 +1,417 @@ +# Custom themes + +A guide to creating and distributing custom themes. + +--- + +The bare minimum required for a custom theme is a `base.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 `base.html`. For example, given this example +project layout: + + mkdocs.yml + docs/ + index.md + about.md + custom_theme/ + base.html + ... + +You would include the following setting to use the custom theme directory: + + theme_dir: 'custom_theme' + +If used in combination with the `theme` 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 `base.html` file +would replace that in the theme but otherwise it would remain the same. This +is useful if you want to make small adjustments to an existing theme. + +## Basic theme + +The simplest `base.html` file is the following: + +```django + + + + {% if page_title %}{{ page_title }} - {% endif %}{{ site_name }} + + + {{ content }} + + +``` + +Article content from each page specified in `mkdocs.yml` is inserted using the +`{{ content }}` tag. Stylesheets 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. + +## 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 in the context map directly the [configuration options +](/user-guide/configuration.md). + +Variable Name | Configuration name +----------------- | ------------------- | +site_name | [site_name] | +site_author | [site_author] | +favicon | [site_favicon] | +page_description | [site_description] | +repo_url | [repo_url] | +repo_name | [repo_name] | +site_url | [site_url] | +extra_css | [extra_css] | +extra_javascript | [extra_javascript] | +extra | [extra] | +include_nav | [include_nav] | +include_next_prev | [include_next_prev] | +copyright | [copyright] | +google_analytics | [google_analytics] | + +[site_name]: ./configuration.md#site_name +[site_author]: ./configuration.md#site_author +[site_favicon]: ./configuration.md#site_favicon +[site_description]: ./configuration.md#site_description +[repo_url]: ./configuration.md#repo_url +[repo_name]: ./configuration.md#repo_name +[site_url]: ./configuration.md#site_url +[extra_css]: ./configuration.md#extra_css +[extra_javascript]: ./configuration.md#extra_javascript +[extra]: ./configuration.md#extra +[include_nav]: ./configuration.md#include_nav +[include_next_prev]: ./configuration.md#include_next_prev +[copyright]: ./configuration.md#copyright +[google_analytics]: ./configuration.md#google_analytics + +The following variables provide information about the navigation and location. + +#### 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 + +``` + +#### 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 + +``` + +#### homepage_url +Provides a relative path to the documentation homepage. + +#### 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 Context +The page context includes all of the above Global context and the following +additional variables. + +#### page_title +Contains the Title for the current page. + +#### page_description +Contains the description for the current page on the homepage, it is blank on +other pages. + +#### content +The rendered Markdown as HTML, this is the contents of the documentation. + +#### 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 + +``` + +#### 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 meta.source %} + + {{ filename }} + +{% endfor %} +``` + +#### canonical_url +The full, canonical URL to the current page. This includes the site_url from +the configuration. + +#### current_page +The page object for the current page. The page path and url properties can be +displayed like this. + +```django +

{{ current_page.title }}

+

This page is at {{ current_page.url }}

+``` + +#### previous_page +The page object for the previous page. The usage is the same as for +`current_page`. + +#### next_page +The page object for the next page.The usage is the same as for `current_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 %} + +{% 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 + + +``` + +!!! 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 +

Search Results

+ +
+ +
+ +
+ Sorry, page not found. +
+``` + +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]. + +[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`. Then a directory with the name +of your theme and containing a `base.html` file and a `__init__.py`. + +```no-highlight +. +|-- MANIFEST.in +|-- theme_name +| |-- base.html +| |-- __init__.py +`-- 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 base.html file +should contain all of the other theme files. The minimum requirement is that +it includes a `base.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.html diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 93ed8e9ecf..869f5c9f1a 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/docs/user-guide/styling-your-docs.md @@ -4,37 +4,54 @@ How to style and theme your documentation. --- -MkDocs includes a number of [different themes](#built-in-themes) which can easily be customised with extra CSS or JavaScript or you can create a [custom theme](#custom-themes) for your documentation. +MkDocs includes a number of different [builtin themes](#built-in-themes) and +[external themes](#bootstrap-and-bootswatch-themes) which can easily be +[customised with extra CSS or JavaScript](#customising-a-theme) or you can +create a [custom theme](/user-guide/custom-themes.md) for your documentation. -To use a theme that is included in MkDocs, simply add this to your `mkdocs.yml` config file. +To use a theme that is included in MkDocs, simply add this to your +`mkdocs.yml` config file. - theme: amelia + theme: readthedocs -Replace [`amelia`](#amelia) with any of the [builtin themes](#built-in-themes) listed below. +Replace [`readthedocs`](#readthedocs) with any of the [builtin themes](#built- +in-themes) listed below. -To customise a theme, simply place additional CSS and JavaScript files in the documentation directory next to the Markdown files and these will be automatically detected and added. Additionally, the [`extra_css`](/user-guide/configuration.md#extra_css) and [`extra_javascript`](/user-guide/configuration.md#extra_javascript) configuration options can be used to specifically include certain CSS or JavaScript files. - -See the [configuration documentation](/user-guide/configuration.md#theme) for more specific details about these options. - -To create a new custom theme or more heavily customise an existing theme, see the [custom themes](#custom-themes) section below. +To create a new custom theme or more heavily customise an existing theme, see +the [custom themes](#custom-themes) section below. ## Built-in themes -### MkDocs +### mkdocs ![mkdocs](/img/mkdocs.png) -### Read the Docs +### readthedocs ![ReadTheDocs](https://docs.readthedocs.org/en/latest/_images/screen_mobile.png) -### Bootstrap +## Bootstrap and Bootswatch Themes -![Bootstrap](http://bootstrapdocs.com/v2.3.1/docs/assets/img/examples/bootstrap-example-fluid.png) +MkDocs also includes themes provided by two packages. [MkDocs Bootstrap] and +[MkDocs Bootswatch]. The Bootstrap theme provides a theme based on [Bootstrap] +and the Bootstrap theme provides 12 different themed Bootstrap themes based on +the [Bootswatch] project. + +!!! note + The Bootstrap and Bootswatch themes will not be included by default from + MkDocs version 1.0. They will need to be installed manually with `pip + install mkdocs-bootstrap` or `pip install mkdocs-bootswatch`. -### The bootswatch themes +[Bootstrap]: http://getbootstrap.com/ +[Bootswatch]: http://bootswatch.com/ +[MkDocs Bootstrap]: http://mkdocs.github.io/mkdocs-bootstrap/ +[MkDocs Bootswatch]: http://mkdocs.github.io/mkdocs-bootswatch/ + +#### Bootstrap + +![Bootstrap](http://bootstrapdocs.com/v2.3.1/docs/assets/img/examples/bootstrap-example-fluid.png) #### Amelia @@ -84,235 +101,37 @@ To create a new custom theme or more heavily customise an existing theme, see th ![Yeti](http://bootswatch.com/yeti/thumbnail.png) -## Custom themes - -The bare minimum required for a custom theme is a `base.html` [Jinja2 template] file. This should be placed in a directory at the same level as the `mkdocs.yml` configuration file. Within `mkdocs.yml`, specify the `theme_dir` option and set it to the name of the directory containing `base.html`. For example, given this example project layout: - - mkdocs.yml - docs/ - index.md - about.md - custom_theme/ - base.html - ... - -You would include the following setting to use the custom theme directory: - - theme_dir: 'custom_theme' - -If used in combination with the `theme` 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 `base.html` file would replace that in the theme but otherwise it would remain the same. This is useful if you want to make small adjustments to an existing theme. - -### Basic theme - -The simplest `base.html` file is the following: - - - - - - - {{ content }} - - - -Article content from each page specified in `mkdocs.yml` is inserted using the `{{ content }}` tag. Stylesheets 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. - -### 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 in the context map directly the the [configuration options](/user-guide/configuration.md). - -Variable Name | Configuration name ------------------ | ------------------- | -site_name | site_name | -site_author | site_author | -favicon | site_favicon | -page_description | site_description | -repo_url | repo_url | -repo_name | repo_name | -site_url | site_url | -extra_css | extra_css | -extra_javascript | extra_javascript | -extra | extra | -include_nav | include_nav | -include_next_prev | include_next_prev | -copyright | copyright | -google_analytics | google_analytics | - -The following variables provide information about the navigation and location. - -##### nav -The `nav` variable is used to create the navigation for for the documentation. Following is a basic usage example which outputs the first and second level navigation as a nested list. - -``` - -``` - -##### 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: - -``` - -``` - -##### homepage_url -Provides a relative path to the documentation homepage. - -##### mkdocs_version -Contains the current MkDocs version. - -##### build_date_utc -A Python datetime object that includes represents the time the documentation was built in UTC. This is useful for showing how recently the documentation was updated. - - -#### Page Context -The page context includes all of the above Global context and the following additional variables. - -##### page_title -Contains the Title for the current page. -##### page_description -Contains the description for the current page on the homepage, it is blank on other pages. +## Customising a Theme -##### content -The rendered Markdown as HTML, this is the contents of the documentation. +The [extra_css] and [extra_javascript] configuration options can be used to +make tweaks and customisations to existing themes. To use these, you simply +need to include either CSS or JavaScript files within your [documentation +directory]. -##### 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. +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; +} ``` - -``` - -##### 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. - -``` -{% for filename in meta.source %} - - {{ filename }} - -{% endfor %} -``` - -##### canonical_url -The full, canonical URL to the current page. This includes the site_url from the configuration. - -##### current_page -The page object for the current page. The page path and url properties can be displayed like this. - -``` -

{{ current_page.title }}

-

This page is at {{ current_page.url }}

-``` - -##### previous_page -The page object for the previous page. The isage is the same as for -`current_page`. - -##### next_page -The page object for the next page.The isage is the same as for `current_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. - -```html -{{ config.extra.version }} - -{% if config.extra.links %} - -{% 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. - - - - -!!! 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. - -

Search Results

- -
- -
-
- Sorry, page not found. -
+!!! Warning -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. + If you are deploying your documentation with [ReadTheDocs]. You will need + to explicitly list the CSS and JavaScript files you want to include inf + your config. To do this, add the following to your mkdocs.yml. + extra_css: [extra.css] -[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/ +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. +[ReadTheDocs]: ./deploying-your-docs.md#readthedocs +[documentation directory]: /user-guide/configuration/#docs_dir +[extra_css]: /user-guide/configuration.md#extra_css +[extra_javascript]: /user-guide/configuration.md#extra_javascript diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index 0614a1825b..acbf186aaa 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -10,28 +10,34 @@ The [pages configuration](/user-guide/configuration.md#pages) in your `mkdocs.ym A simple pages configuration looks like this: - pages: - - 'index.md' - - 'about.md' +```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. - pages: - - Home: 'index.md' - - About: 'about.md' +```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: - 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' +```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. @@ -44,41 +50,51 @@ Your documentation source should be written as regular Markdown files, and place The simplest project you can create will look something like this: - mkdocs.yml - docs/ - index.md +```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: - mkdocs.yml - docs/ - index.md - about.md - license.md +```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: - / - /about/ - /license/ +```no-highlight +/ +/about/ +/license/ +``` You can also include your Markdown files in nested directories if that better suits your documentation layout. - docs/ - index.md - user-guide/getting-started.md - user-guide/configuration-options.md - license.md +```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: - / - /user-guide/getting-started/ - /user-guide/configuration-options/ - /license/ +```no-highlight +/ +/user-guide/getting-started/ +/user-guide/configuration-options/ +/license/ +``` ## Linking documents @@ -109,22 +125,26 @@ As well as the Markdown source files, you can also include other file types in y For example, if your project documentation needed to include a [GitHub pages CNAME file](https://help.github.com/articles/setting-up-a-custom-domain-with-pages#setting-the-domain-in-your-repo) and a PNG formatted screenshot image then your file layout might look as follows: - mkdocs.yml - docs/ - CNAME - index.md - about.md - license.md - img/ - screenshot.png +```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: - Cupcake indexer is a snazzy new project for indexing small cakes. +```Markdown +Cupcake indexer is a snazzy new project for indexing small cakes. - ![Screenshot](img/screenshot.png) +![Screenshot](img/screenshot.png) - *Above: Cupcake indexer in progress* +*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. @@ -136,7 +156,7 @@ MkDocs supports the following Markdown extensions. A simple table looks like this: -```text +```no-highlight First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell @@ -145,7 +165,7 @@ Content Cell | Content Cell | Content Cell If you wish, you can add a leading and tailing pipe to each line of the table: -```text +```no-highlight | First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | @@ -154,7 +174,7 @@ If you wish, you can add a leading and tailing pipe to each line of the table: Specify alignment for each column by adding colons to separator lines: -```text +```no-highlight First Header | Second Header | Third Header :----------- | :-----------: | -----------: Left | Center | Right @@ -165,17 +185,21 @@ Left | Center | Right Start with a line containing 3 or more backtick \` characters, and ends with the first line with the same number of backticks \`: - ``` - Fenced code blocks are like Stardard - Markdown’s regular code blocks, except that - they’re not indented and instead rely on a - start and end fence lines to delimit the code - block. - ``` +```no-highlight + ``` + Fenced code blocks are like Stardard + Markdown’s regular code blocks, except that + they’re not indented and instead rely on a + start and end fence lines to delimit the code + block. + ``` +``` With the approach, the language can be specified on the first line after the backticks: - ```python - def fn(): +```no-highlight + ```python + def fn(): pass - ``` + ``` +``` diff --git a/mkdocs.yml b/mkdocs.yml index 46bab44715..0a06b5942c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,8 @@ pages: - 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 + - 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