diff --git a/.markdownlintrc b/.markdownlintrc index 620a42b6..8a3a069d 100644 --- a/.markdownlintrc +++ b/.markdownlintrc @@ -12,5 +12,8 @@ "MD007": { "indent": 4 }, // Exclude code block style - "MD046": false + "MD046": false, + + // Allow inline HTML + "MD033": false } diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 60a2ad91..cf40ab99 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -67,7 +67,7 @@ MkDocs can now benefit from recent bug fixes and new features, including the fol Plugin developers can now use the `on_build_error` hook to execute code when an exception is raised while building the site. -See [`on_build_error`](../user-guide/plugins.md#on_build_error) +See [`on_build_error`](../dev-guide/plugins.md#on_build_error) in the Plugins documentation for details. #### Two new exceptions: BuildError and PluginError (#2103) @@ -80,7 +80,7 @@ MkDocs now has two new exceptions defined in `mkdocs.exceptions`, * `BuildError` should not be used by third-party plugins developers and is reserved for internal use only. -See [`Handling errors`](../user-guide/plugins.md#handling-errors) +See [`Handling errors`](../dev-guide/plugins.md#handling-errors) in the Plugins documentation for details. #### Search Indexing Strategy configuration @@ -119,6 +119,7 @@ up horizontal space for better rendering of content like tables (#2193). property to accomodate this possible dynamic behavior. See #2305. * Updated highlight.js to 10.5.0. See #2313. * Bugfix: Search plugin now works with Japanese language. See #2178. +* Documentation has been refactored (#1629). ## Version 1.1.2 (2020-05-14) @@ -162,7 +163,7 @@ mirror the upstream configuration options. See the [theme documentation][rtd-docs] for details. [upstream]: https://github.com/rtfd/sphinx_rtd_theme/ -[rtd-docs]: ../user-guide/styling-your-docs.md#readthedocs +[rtd-docs]: ../user-guide/choosing-your-theme.md#readthedocs #### Update `mkdocs` theme to Bootswatch 4.1.3 (#1563) @@ -278,7 +279,7 @@ The changes included in the refactor are summarized below. files not in the `docs_dir`, exclude files, redefine page URLs (i.e. implement extensionless URLs), or to manipulate files in various other ways. - [on_files]: ../user-guide/plugins.md#on_files +[on_files]: ../dev-guide/plugins.md#on_files ##### Backward Incompatible Changes @@ -384,8 +385,8 @@ need to will be altered. {% endfor %} ``` -[base_url]: ../user-guide/custom-themes.md#base_url -[url]: ../user-guide/custom-themes.md#url +[base_url]: ../dev-guide/themes.md#base_url +[url]: ../dev-guide/themes.md#url #### Path Based Settings are Relative to Configuration File (#543) @@ -453,7 +454,7 @@ Users can review the [configuration options][search config] available and theme authors should review how [search and themes] interact. [search config]: ../user-guide/configuration.md#search -[search and themes]: ../user-guide/custom-themes.md#search_and_themes +[search and themes]: ../dev-guide/themes.md#search_and_themes #### `theme_dir` Configuration Option fully Deprecated @@ -537,7 +538,7 @@ then the `search` plugin will be included by default. See the [configuration][plugin_config] documentation for information on overriding the default. -[Plugin API]: ../user-guide/plugins.md +[Plugin API]: ../dev-guide/plugins.md [plugin_config]: ../user-guide/configuration.md#plugins #### Theme Customization. (#1164) @@ -574,7 +575,7 @@ theme: See the [theme] configuration option documentation for details. -[Theme Configuration]: ../user-guide/custom-themes.md#theme-configuration +[Theme Configuration]: ../dev-guide/themes.md#theme-configuration [theme]: ../user-guide/configuration.md#theme [custom_dir]: ../user-guide/configuration.md#custom_dir @@ -592,7 +593,7 @@ template exists. ##### Context Variables Page specific variable names in the template context have been refactored as -defined in [Custom Themes](../user-guide/custom-themes.md#page). The +defined in [Custom Themes](../dev-guide/themes.md#page). The old variable names issued a warning in version 0.16, but have been removed in version 1.0. @@ -610,14 +611,14 @@ user created and third-party templates: | previous_page | [page.previous_page]| | next_page | [page.next_page] | -[page]: ../user-guide/custom-themes.md#page -[page.title]: ../user-guide/custom-themes.md#pagetitle -[page.content]: ../user-guide/custom-themes.md#pagecontent -[page.toc]: ../user-guide/custom-themes.md#pagetoc -[page.meta]: ../user-guide/custom-themes.md#pagemeta -[page.canonical_url]: ../user-guide/custom-themes.md#pagecanonical_url -[page.previous_page]: ../user-guide/custom-themes.md#pageprevious_page -[page.next_page]: ../user-guide/custom-themes.md#pagenext_page +[page]: ../dev-guide/themes.md#page +[page.title]: ../dev-guide/themes.md#pagetitle +[page.content]: ../dev-guide/themes.md#pagecontent +[page.toc]: ../dev-guide/themes.md#pagetoc +[page.meta]: ../dev-guide/themes.md#pagemeta +[page.canonical_url]: ../dev-guide/themes.md#pagecanonical_url +[page.previous_page]: ../dev-guide/themes.md#pageprevious_page +[page.next_page]: ../dev-guide/themes.md#pagenext_page Additionally, a number of global variables have been altered and/or removed and user created and third-party templates should be updated as outlined below: @@ -697,7 +698,7 @@ the `extra_css` or `extra_javascript` config settings going forward. ##### Page Context Page specific variable names in the template context have been refactored as -defined in [Custom Themes](../user-guide/custom-themes.md#page). The +defined in [Custom Themes](../dev-guide/themes.md#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. @@ -715,14 +716,14 @@ user created and third-party templates: | previous_page | [page.previous_page]| | next_page | [page.next_page] | -[page]: ../user-guide/custom-themes.md#page -[page.title]: ../user-guide/custom-themes.md#pagetitle -[page.content]: ../user-guide/custom-themes.md#pagecontent -[page.toc]: ../user-guide/custom-themes.md#pagetoc -[page.meta]: ../user-guide/custom-themes.md#pagemeta -[page.canonical_url]: ../user-guide/custom-themes.md#pagecanonical_url -[page.previous_page]: ../user-guide/custom-themes.md#pageprevious_page -[page.next_page]: ../user-guide/custom-themes.md#pagenext_page +[page]: ../dev-guide/themes.md#page +[page.title]: ../dev-guide/themes.md#pagetitle +[page.content]: ../dev-guide/themes.md#pagecontent +[page.toc]: ../dev-guide/themes.md#pagetoc +[page.meta]: ../dev-guide/themes.md#pagemeta +[page.canonical_url]: ../dev-guide/themes.md#pagecanonical_url +[page.previous_page]: ../dev-guide/themes.md#pageprevious_page +[page.next_page]: ../dev-guide/themes.md#pagenext_page ##### Global Context @@ -811,7 +812,7 @@ 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.md#overriding-template-blocks +[blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks #### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986) @@ -929,12 +930,12 @@ 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 +See the documentation for [Customizing Your Theme] for more information about using and customizing 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 +[Customizing Your Theme]: ../user-guide/customizing-your-theme.md +[Custom themes]: ../dev-guide/themes.md ### Other Changes and Additions to Version 0.15.0 @@ -957,7 +958,7 @@ themes [site_description]: ../user-guide/configuration.md#site_description [site_author]: ../user-guide/configuration.md#site_author -[ReadTheDocs]: ../user-guide/styling-your-docs.md#readthedocs +[ReadTheDocs]: ../user-guide/choosing-your-theme.md#readthedocs ## Version 0.14.0 (2015-06-09) @@ -1042,7 +1043,7 @@ JavaScript library [lunr.js]. It has been added to both the `mkdocs` and for adding it to your own themes. [lunr.js]: https://lunrjs.com/ -[supporting search]: ../user-guide/styling-your-docs.md#search-and-themes +[supporting search]: ../dev-guide/themes.md#search-and-themes #### New Command Line Interface @@ -1073,7 +1074,7 @@ 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 +[global variables]: ../dev-guide/themes.md#global-context ### Other Changes and Additions to Version 0.13.0 diff --git a/docs/css/extra.css b/docs/css/extra.css index 29f4d9a4..cf2d58e5 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -25,3 +25,25 @@ code.no-highlight { dd { padding-left: 20px; } + +/* Homepage */ + +body.homepage div.jumbotron { + margin-top: 1.5rem; + padding-top: 1rem; + padding-bottom: 0; +} + +body.homepage div.jumbotron div.card { + margin-bottom: 2rem; +} + +body.homepage>div.container>div.row>div.col-md-3 { + display: none; +} + +body.homepage>div.container>div.row>div.col-md-9 { + margin-left: 0; + flex: 0 0 100%; + max-width: 100%; +} diff --git a/docs/dev-guide/index.md b/docs/dev-guide/index.md new file mode 100644 index 00000000..f0124c90 --- /dev/null +++ b/docs/dev-guide/index.md @@ -0,0 +1,16 @@ +# Developer Guide + +Extending MkDocs + +--- + +The MkDocs Developer Guide provides documentation for developers of third +party themes and plugins. Please see the [Contributing Guide] for information +on contributing to MkDocs itself. You can jump directly to a page listed +below, or use the *next* and *previous* buttons in the navigation bar at the +top of the page to move through the documention in order. + +- [Themes](themes.md) +- [Plugins](plugins.md) + +[Contributing Guide]: ../about/contributing.md diff --git a/docs/user-guide/plugins.md b/docs/dev-guide/plugins.md similarity index 98% rename from docs/user-guide/plugins.md rename to docs/dev-guide/plugins.md index adaed745..efbda3ae 100644 --- a/docs/user-guide/plugins.md +++ b/docs/dev-guide/plugins.md @@ -472,16 +472,16 @@ Note that registering a plugin does not activate it. The user still needs to tell MkDocs to use it via the config. [BasePlugin]:#baseplugin -[config]: configuration.md#plugins +[config]: ../user-guide/configuration.md#plugins [entry point]: #entry-point [env]: #on_env [events]: #events -[extra_templates]: configuration.md#extra_templates +[extra_templates]: ../user-guide/configuration.md#extra_templates [Global Events]: #global-events [Page Events]: #page-events [post_build]: #on_post_build [post_template]: #on_post_template -[static_templates]: configuration.md#static_templates +[static_templates]: ../user-guide/configuration.md#static_templates [Template Events]: #template-events [MkDocs Plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins [on_build_error]: #on_build_error diff --git a/docs/user-guide/custom-themes.md b/docs/dev-guide/themes.md similarity index 92% rename from docs/user-guide/custom-themes.md rename to docs/dev-guide/themes.md index 96aec56a..26e352a7 100644 --- a/docs/user-guide/custom-themes.md +++ b/docs/dev-guide/themes.md @@ -1,4 +1,4 @@ -# Custom themes +# Developing Themes A guide to creating and distributing custom themes. @@ -6,24 +6,27 @@ 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. + If you are looking for existing third party themes, they are listed in the + MkDocs [community wiki]. 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. +this base theme on [GitHub][basic theme]**. It contains detailed comments in +the code to describe the different features and their usage. + +[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes +[basic theme]: https://github.com/mkdocs/mkdocs-basic-theme ## Creating a custom theme -The bare minimum required for a custom theme is a `main.html` [Jinja2 template] -file which is placed in a directory that is *not* a child of the [docs_dir]. -Within `mkdocs.yml`, set the theme.[custom_dir] option to the path of the -directory containing `main.html`. The path should be relative to the -configuration file. For example, given this example project layout: +The bare minimum required for a custom theme is a `main.html` [Jinja2 +template] file which is placed in a directory that is *not* a child of the +[docs_dir]. Within `mkdocs.yml`, set the [`theme.custom_dir`][custom_dir] +option to the path of the directory containing `main.html`. The path should be +relative to the configuration file. For example, given this example project +layout: ```no-highlight mkdocs.yml @@ -56,7 +59,7 @@ theme: `mkdocs` theme would remain unchanged. This is useful if you want to make small adjustments to an existing theme. - For more specific information, see [styling your docs]. + For more specific information, see [Customizing Your Theme]. !!! Warning @@ -69,13 +72,13 @@ theme: the `theme.name` configuration option, then a `mkdocs_theme.yml` file is required for the theme. -[styling your docs]: ./styling-your-docs.md#using-the-theme-custom_dir -[custom_dir]: ./configuration.md#custom_dir -[name]: ./configuration.md#name -[docs_dir]:./configuration.md#docs_dir +[Customizing Your Theme]: ../user-guide/customizing-your-theme.md#using-the-theme-custom_dir +[custom_dir]: ../user-guide/configuration.md#custom_dir +[name]: ../user-guide/configuration.md#name +[docs_dir]: ../user-guide/configuration.md#docs_dir [configuration]: #theme-configuration [packaged]: #packaging-themes -[theme]: ./configuration.md#theme +[theme]: ../user-guide/configuration.md#theme ## Basic theme @@ -114,8 +117,8 @@ with one of the [built-in themes] and modify it accordingly. [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 +[theme_dir]: ../user-guide/customizing-your-theme.md#using-the-theme_dir +[blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks ## Theme Files @@ -177,16 +180,16 @@ 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.extra_javascript](./configuration.md#extra_javascript) -* [config.extra_css](./configuration.md#extra_css) -* [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) +* [config.site_name](../user-guide/configuration.md#site_name) +* [config.site_url](../user-guide/configuration.md#site_url) +* [config.site_author](../user-guide/configuration.md#site_author) +* [config.site_description](../user-guide/configuration.md#site_description) +* [config.extra_javascript](../user-guide/configuration.md#extra_javascript) +* [config.extra_css](../user-guide/configuration.md#extra_css) +* [config.repo_url](../user-guide/configuration.md#repo_url) +* [config.repo_name](../user-guide/configuration.md#repo_name) +* [config.copyright](../user-guide/configuration.md#copyright) +* [config.google_analytics](../user-guide/configuration.md#google_analytics) #### nav @@ -194,7 +197,7 @@ The `nav` variable is used to create the navigation for the documentation. The `nav` object is an iterable of [navigation objects](#navigation-objects) as defined by the [nav] configuration setting. -[nav]: configuration.md#nav +[nav]: ../user-guide/configuration.md#nav In addition to the iterable of [navigation objects](#navigation-objects), the `nav` object contains the following attributes: @@ -357,7 +360,7 @@ For example, if `site_url: https://example.com/`, then the value of `site_url: https://example.com/bar/`, then the value of `page.abs_url` for the page `foo.md` would be `/bar/foo/`. -[site_url]: ./configuration.md#site_url +[site_url]: ../user-guide/configuration.md#site_url ##### page.canonical_url @@ -526,7 +529,7 @@ link objects. ### Extra Context Additional variables can be passed to the template with the -[`extra`](./configuration.md#extra) configuration option. This is a +[`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 @@ -692,8 +695,8 @@ index when it is available. The `index` object was new in MkDocs version *1.0*. [built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes [theme's configuration file]: #theme-configuration [lunr.js]: https://lunrjs.com/ -[site_dir]: configuration.md#site_dir -[prebuild_index]: configuration.md#prebuild_index +[site_dir]: ../user-guide/configuration.md#site_dir +[prebuild_index]: ../user-guide/configuration.md#prebuild_index ## Packaging Themes @@ -866,4 +869,4 @@ 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/ -[theme]: ./configuration.md#theme +[theme]: ../user-guide/configuration.md#theme diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..8e680e66 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,209 @@ +# Getting Started with MkDocs + +An introductory tutorial! + +--- + +## Installation + +To install MkDocs, run the following command from the command line: + +```bash +pip install mkdocs +``` + +For more details, see the [Installation Guide]. + +## Creating a new project + +Getting started is super easy. To create a new project, run the following +command from the command line: + +```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 (`docs` is +the default value for the [docs_dir] configuration setting). 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 [`nav`][nav] +setting: + +```yaml +site_name: MkLorum +nav: + - 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 all of 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 +nav: + - 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 the `docs` directory and copy your custom `favicon.ico` +file to that directory. MkDocs will automatically 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 its +documentation on how to ignore specific directories. + +## 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. Simply 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 + +See the [User Guide] for more complete documentation of all of MkDocs' features. + +To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues]. + +[Installation Guide]: user-guide/installation.md +[docs_dir]: user-guide/configuration.md#docs_dir +[deploy]: user-guide/deploying-your-docs.md +[nav]: user-guide/configuration.md#nav +[GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions +[GitHub issues]: https://github.com/mkdocs/mkdocs/issues +[site_name]: user-guide/configuration.md#site_name +[theme]: user-guide/configuration.md#theme +[User Guide]: user-guide/index.md diff --git a/docs/index.md b/docs/index.md index 0c4279a5..43cebdb0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,360 +4,86 @@ Project documentation with Markdown. --- -## Overview - MkDocs is a **fast**, **simple** and **downright gorgeous** static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML -configuration file. Start by reading the introduction below, then check the User -Guide for more info. - -### 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 listed on the [MkDocs Themes] wiki page, 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] and/or installing some [plugins]. - ---- - -## 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]: https://brew.sh/ -[dnf]: https://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 3.8.2 -$ pip --version -pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) -``` - -MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3. - -#### 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 would like manpages installed for MkDocs, the [click-man] tool can - generate and install them for you. Simply run the following two commands: - - pip install click-man - click-man --target path/to/man/pages mkdocs - - See the [click-man documentation] for an explanation of why manpages are - not automatically generated and installed by pip. - -[click-man]: https://github.com/click-contrib/click-man -[click-man documentation]: https://github.com/click-contrib/click-man#automatic-man-page-installation-with-setuptools-and-pip - -!!! 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:\Python38\`), 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 (`docs` is -the default value for the [docs_dir] configuration setting). Right now the `docs` -folder just contains a single documentation page, named `index.md`. - -[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir - -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 [`nav`][nav] -setting: - -```yaml -site_name: MkLorum -nav: - - 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 all of 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 -nav: - - 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 the `docs` directory and copy your custom `favicon.ico` -file to that directory. MkDocs will automatically 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 its -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. Simply 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 [GitHub discussions] or [GitHub issues]. - -[deploy]: user-guide/deploying-your-docs/ -[mkdocs]: user-guide/styling-your-docs/#mkdocs -[readthedocs]: user-guide/styling-your-docs/#readthedocs -[theme]: user-guide/styling-your-docs/ -[themes]: user-guide/styling-your-docs/ -[plugins]: user-guide/plugins/ -[MkDocs Themes]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes -[build your own]: user-guide/custom-themes/ -[get-pip.py]: https://bootstrap.pypa.io/get-pip.py -[nav]: user-guide/configuration/#nav -[GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions -[GitHub issues]: https://github.com/mkdocs/mkdocs/issues -[pip]: https://pip.readthedocs.io/en/stable/installing/ -[Python]: https://www.python.org/ -[site_name]: user-guide/configuration/#site_name -[theme]: user-guide/configuration/#theme +configuration file. Start by reading the [introductory tutorial], then check the +[User Guide] for more information. + +[introductory tutorial]: getting-started.md +[User Guide]: user-guide/index.md + +
+Getting Started +User Guide +
+ +
+

Features

+ +
+
+
+
+

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 third-party themes listed on the MkDocs Themes wiki page, or build your + own. +

+
+
+
+
+
+
+

Easy to customize

+

+ Get your project documentation looking just the way you want it by + customizing your + theme and/or installing some plugins. Modify + Markdown's behavior with Markdown + extensions. Many configuration options are + available. +

+
+
+
+
+ +
+
+
+
+

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. +

+
+
+
+
+
+
+

Host anywhere

+

+ MkDocs builds completely static HTML sites that you can host on + GitHub pages, Amazon S3, or anywhere else you + choose. +

+
+
+
+
+
diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md new file mode 100644 index 00000000..7c326e50 --- /dev/null +++ b/docs/user-guide/choosing-your-theme.md @@ -0,0 +1,136 @@ +# Choosing your Theme + +Selecting and configuring a theme. + +--- + +MkDocs includes two built-in themes ([mkdocs](#mkdocs) and +[readthedocs](#readthedocs)), as documented below. However, many [third party +themes] are available to choose from as well. + +To choose a theme, set the [theme] configuration option in your `mkdocs.yml` +config file. + +```yaml +theme: + name: readthedocs +``` + +## mkdocs + +The default theme, which was built as a custom [Bootstrap] theme, supports most +every feature of MkDocs. + +![mkdocs](../img/mkdocs.png) + +In addition to the default [theme configuration options][theme], the `mkdocs` theme +supports the following options: + +* __`highlightjs`__: Enables highlighting of source code in code blocks using + the [highlight.js] JavaScript library. Default: `True`. + +* __`hljs_style`__: The highlight.js library provides 79 different [styles] + (color variations) for highlighting source code in code blocks. Set this to + the name of the desired style. Default: `github`. + +* __`hljs_languages`__: By default, highlight.js only supports 23 common + languages. List additional languages here to include support for them. + + theme: + name: mkdocs + highlightjs: true + hljs_languages: + - yaml + - rust + +* __`shortcuts`__: Defines keyboard shortcut keys. + + theme: + name: mkdocs + shortcuts: + help: 191 # ? + next: 78 # n + previous: 80 # p + search: 83 # s + + All values must be numeric key codes. It is best to use keys which are + available on all keyboards. You may use to determine + the key code for a given key. + + * __`help`__: Display a help modal which lists the keyboard shortcuts. + Default: `191` (?) + + * __`next`__: Navigate to the "next" page. Default: `78` (n) + + * __`previous`__: Navigate to the "previous" page. Default: `80` (p) + + * __`search`__: Display the search modal. Default: `83` (s) + +* __`navigation_depth`__: The maximum depth of the navigation tree in the + sidebar. Default: `2`. + +* __`nav_style`__: This adjusts the visual style for the top navigation bar; by + default, this is set to `primary` (the default), but it can also be set to + `dark` or `light`. + + theme: + name: mkdocs + nav_style: dark + +## readthedocs + +A clone of the default theme used by the [Read the Docs] service, which offers +the same restricted feature-set as its parent theme. Like its parent theme, only +two levels of navigation are supported. + +![ReadTheDocs](../img/readthedocs.png) + +In addition to the default [theme configuration options][theme], the `readthedocs` +theme supports the following options: + +* __`highlightjs`__: Enables highlighting of source code in code blocks using + the [highlight.js] JavaScript library. Default: `True`. + +* __`hljs_languages`__: By default, highlight.js only supports 23 common + languages. List additional languages here to include support for them. + + theme: + name: readthedocs + highlightjs: true + hljs_languages: + - yaml + - rust + +* __`include_homepage_in_sidebar`__: Lists the homepage in the sidebar menu. As + MkDocs requires that the homepage be listed in the `nav` configuration + option, this setting allows the homepage to be included or excluded from + the sidebar. Note that the site name/logo always links to the homepage. + Default: `True`. + +* __`prev_next_buttons_location`__: One of `bottom`, `top`, `both` , or `none`. + Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`. + +* __`navigation_depth`__: The maximum depth of the navigation tree in the + sidebar. Default: `4`. + +* __`collapse_navigation`__: Only include the page section headers in the + sidebar for the current page. Default: `True`. + +* __`titles_only`__: Only include page titles in the sidebar, excluding all + section headers for all pages. Default: `False`. + +* __`sticky_navigation`__: If True, causes the sidebar to scroll with the main + page content as you scroll the page. Default: `True`. + +## 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. + +[third party themes]: #third-party-themes +[theme]: configuration.md#theme +[Bootstrap]: https://getbootstrap.com/ +[highlight.js]: https://highlightjs.org/ +[styles]: https://highlightjs.org/static/demo/ +[Read the Docs]: https://readthedocs.org/ +[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 27c818b1..35e65e48 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -263,7 +263,7 @@ Sets the theme and theme specific configuration of your documentation site. May be either a string or a set of key/value pairs. If a string, it must be the string name of a known installed theme. For a list -of available themes visit [styling your docs]. +of available themes visit [Choosing Your Theme]. An example set of key/value pairs might look something like this: @@ -283,7 +283,7 @@ If a set of key/value pairs, the following nested keys can be defined: #### name: The string name of a known installed theme. For a list of available themes - visit [styling your docs]. + visit [Choosing Your Theme]. #### custom_dir: @@ -292,11 +292,11 @@ If a set of key/value pairs, the following nested keys can be defined: your configuration file or it can be an absolute directory path from the root of your local file system. - See [styling your docs][theme_dir] for details if you would like to tweak an + See [Customizing Your Theme][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. + See the [Theme Developer Guide] if you would like to build your own theme + from the ground up. #### static_templates: @@ -650,18 +650,18 @@ plugins: **default**: `full` -[custom themes]: custom-themes.md -[variables that are available]: custom-themes.md#template-variables +[Theme Developer Guide]: ../dev-guide/themes.md +[variables that are available]: ../dev-guide/themes.md#template-variables [pymdk-extensions]: https://python-markdown.github.io/extensions/ [pymkd]: https://python-markdown.github.io/ [smarty]: https://python-markdown.github.io/extensions/smarty/ [exts]: https://python-markdown.github.io/extensions/ [3rd]: https://github.com/Python-Markdown/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 +[theme_dir]: customizing-your-theme.md#using-the-theme_dir +[choosing your theme]: choosing-your-theme.md [extra_css]: #extra_css -[Plugins]: plugins.md +[Plugins]: ../dev-guide/plugins.md [lunr.js]: https://lunrjs.com/ [ISO 639-1]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes [Lunr Languages]: https://github.com/MihaiValentin/lunr-languages#lunr-languages----- diff --git a/docs/user-guide/customizing-your-theme.md b/docs/user-guide/customizing-your-theme.md new file mode 100644 index 00000000..32057056 --- /dev/null +++ b/docs/user-guide/customizing-your-theme.md @@ -0,0 +1,231 @@ +# Customizing Your Theme + +Altering a theme to suit your needs. + +--- + +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](#using-the-docs_dir). +However, for more complex customizations, including overriding templates, you +will need to [use the theme custom_dir](#using-the-theme-custom_dir) setting. + +## 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 [custom_dir]. + +## Using the theme custom_dir + +The [`theme.custom_dir`][custom_dir] configuration option can be used to point +to a directory of files which override the files in a parent theme. The parent +theme would be the theme defined in the [`theme.name`][name] configuration +option. Any file in the `custom_dir` with the same name as a file in the +parent theme will replace the file of the same name in the parent theme. Any +additional files in the `custom_dir` will be added to the parent theme. The +contents of the `custom_dir` should mirror the directory structure of the +parent 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.name` setting must be set to a known + installed theme. If the `name` setting is instead set to `null` (or not + defined), then there is no theme to override and the contents of the + `custom_dir` must be a complete, standalone theme. See the [Theme + Developer Guide][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: + name: mkdocs + custom_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 [Theme Developer Guide][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 parent theme (defined in `name`) but not + included in the `custom_dir` will still be utilized. The `custom_dir` will + only override/replace files in the parent theme. If you want to remove + files, or build a theme from scratch, then you should review the [Theme + Developer Guide][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 `custom_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 htmltitle %} +Custom title goes here +{% endblock %} +``` + +In the above example, the `htmltitle` block defined in your custom `main.html` file +will be used in place of the default `htmltitle` 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 `` 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_button`: 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 +explanation of blocks, consult the [Jinja documentation]. + +### Combining the custom_dir and Template Blocks + +Adding a JavaScript library to the `custom_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() }} + +{% 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 `custom_dir`. The same would be required for +any additional CSS files included in the `custom_dir`. + +[custom theme]: ../dev-guide/themes.md +[extra_css]: ./configuration.md#extra_css +[extra_javascript]: ./configuration.md#extra_javascript +[documentation directory]: ./configuration.md#docs_dir +[ReadTheDocs]: ./deploying-your-docs.md#readthedocs +[custom_dir]: ./configuration.md#custom_dir +[name]: ./configuration.md#name +[mkdocs]: ./choosing-your-theme.md#mkdocs +[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs +[Template Variables]: ../dev-guide/themes.md#template-variables +[Jinja documentation]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance +[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks +[base_url]: ../dev-guide/themes.md#base_url diff --git a/docs/user-guide/deploying-your-docs.md b/docs/user-guide/deploying-your-docs.md index f4698b56..5f3eccc0 100644 --- a/docs/user-guide/deploying-your-docs.md +++ b/docs/user-guide/deploying-your-docs.md @@ -132,7 +132,7 @@ public repository. [rtd]: https://readthedocs.org/ [instructions]: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html [features]: https://docs.readthedocs.io/en/latest/features.html -[theme]: ./styling-your-docs.md#readthedocs +[theme]: ./choosing-your-theme.md#readthedocs ## Other Providers diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md new file mode 100644 index 00000000..dbd28a4b --- /dev/null +++ b/docs/user-guide/index.md @@ -0,0 +1,19 @@ +# User Guide + +Building Documentation with MkDocs + +--- + +The MkDocs Developer Guide provides documentation for users of MkDocs. See +[Getting Started] for an intorductory totorial. You can jump directly to a +page listed below, or use the *next* and *previous* buttons in the navigation +bar at the top of the page to move through the documention in order. + +- [Installation](installation.md) +- [Writing Your Docs](writing-your-docs.md) +- [Choosing Your Theme](choosing-your-theme.md) +- [Customizing Your Theme](customizing-your-theme.md) +- [Configuration](configuration.md) +- [Deploying Your Docs](deploying-your-docs.md) + +[Getting Started]: ../getting-started.md diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md new file mode 100644 index 00000000..2748f6fd --- /dev/null +++ b/docs/user-guide/installation.md @@ -0,0 +1,104 @@ +# MkDocs Installation + +A detailed guide. + +--- + +## Requirements + +MkDocs requires a recent version of [Python] and the the Python package +manager, [pip], to be installed on your system. + +You can check if you already have these installed from the command line: + +```bash +$ python --version +Python 3.8.2 +$ pip --version +pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) +``` + +If you already have those packages installed, you may skip down to [Installing +MkDocs](#installing-mkdocs). + +### Installing Python + +Install [Python] using your package manager of choice, or 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) + +### 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 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8) +``` + +!!! Note + If you would like manpages installed for MkDocs, the [click-man] tool can + generate and install them for you. Simply run the following two commands: + + pip install click-man + click-man --target path/to/man/pages mkdocs + + See the [click-man documentation] for an explanation of why manpages are + not automatically generated and installed by pip. + +!!! 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:\Python38\`), open the + `Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double + clicking on it. Alternatively, you can download the [script][a2p] and run it + (`python win_add2path.py`). + +[Python]: https://www.python.org/ +[python.org]: https://www.python.org/downloads/ +[pip]: https://pip.readthedocs.io/en/stable/installing/ +[get-pip.py]: https://bootstrap.pypa.io/get-pip.py +[click-man]: https://github.com/click-contrib/click-man +[click-man documentation]: https://github.com/click-contrib/click-man#automatic-man-page-installation-with-setuptools-and-pip +[a2p]: https://github.com/python/cpython/blob/master/Tools/scripts/win_add2path.py diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md deleted file mode 100644 index b605a130..00000000 --- a/docs/user-guide/styling-your-docs.md +++ /dev/null @@ -1,373 +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's [custom_dir]. You can also -create your own [custom theme] from the ground 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 - -The default theme, which was built as a custom [Bootstrap] theme, supports most -every feature of MkDocs. - -![mkdocs](../img/mkdocs.png) - -In addition to the default [theme configuration options], the `mkdocs` theme -supports the following options: - -* __`highlightjs`__: Enables highlighting of source code in code blocks using - the [highlight.js] JavaScript library. Default: `True`. - -* __`hljs_style`__: The highlight.js library provides 79 different [styles] - (color variations) for highlighting source code in code blocks. Set this to - the name of the desired style. Default: `github`. - -* __`hljs_languages`__: By default, highlight.js only supports 23 common - languages. List additional languages here to include support for them. - - theme: - name: mkdocs - highlightjs: true - hljs_languages: - - yaml - - rust - -* __`shortcuts`__: Defines keyboard shortcut keys. - - theme: - name: mkdocs - shortcuts: - help: 191 # ? - next: 78 # n - previous: 80 # p - search: 83 # s - - All values must be numeric key codes. It is best to use keys which are - available on all keyboards. You may use to determine - the key code for a given key. - - * __`help`__: Display a help modal which lists the keyboard shortcuts. - Default: `191` (?) - - * __`next`__: Navigate to the "next" page. Default: `78` (n) - - * __`previous`__: Navigate to the "previous" page. Default: `80` (p) - - * __`search`__: Display the search modal. Default: `83` (s) - -* __`navigation_depth`__: The maximum depth of the navigation tree in the - sidebar. Default: `2`. - -* __`nav_style`__: This adjusts the visual style for the top navigation bar; by - default, this is set to `primary` (the default), but it can also be set to - `dark` or `light`. - - theme: - name: mkdocs - nav_style: dark - -[styles]: https://highlightjs.org/static/demo/ - -### readthedocs - -A clone of the default theme used by the [Read the Docs] service, which offers -the same restricted feature-set as its parent theme. Like its parent theme, only -two levels of navigation are supported. - -![ReadTheDocs](../img/readthedocs.png) - -In addition to the default [theme configuration options], the `readthedocs` -theme supports the following options: - -* __`highlightjs`__: Enables highlighting of source code in code blocks using - the [highlight.js] JavaScript library. Default: `True`. - -* __`hljs_languages`__: By default, highlight.js only supports 23 common - languages. List additional languages here to include support for them. - - theme: - name: readthedocs - highlightjs: true - hljs_languages: - - yaml - - rust - -* __`include_homepage_in_sidebar`__: Lists the homepage in the sidebar menu. As - MkDocs requires that the homepage be listed in the `nav` configuration - option, this setting allows the homepage to be included or excluded from - the sidebar. Note that the site name/logo always links to the homepage. - Default: `True`. - -* __`prev_next_buttons_location`__: One of `bottom`, `top`, `both` , or `none`. - Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`. - -* __`navigation_depth`__: The maximum depth of the navigation tree in the - sidebar. Default: `4`. - -* __`collapse_navigation`__: Only include the page section headers in the - sidebar for the current page. Default: `True`. - -* __`titles_only`__: Only include page titles in the sidebar, excluding all - section headers for all pages. Default: `False`. - -* __`sticky_navigation`__: If True, causes the sidebar to scroll with the main - page content as you scroll the page. Default: `True`. - -### 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 -[custom_dir] setting. - -### 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 [custom_dir]. - -### Using the theme custom_dir - -The theme.[custom_dir] configuration option can be used to point to a directory -of files which override the files in a parent theme. The parent theme would be -the theme defined in the theme.[name] configuration option. Any file in the -`custom_dir` with the same name as a file in the parent theme will replace the -file of the same name in the parent theme. Any additional files in the -`custom_dir` will be added to the parent theme. The contents of the `custom_dir` -should mirror the directory structure of the parent 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 `name` setting must be set to a known installed theme. - If the `name` setting is instead set to `null` (or not defined), then there - is no theme to override and the contents of the `custom_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: - name: mkdocs - custom_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 parent theme (defined in `name`) but not included - in the `custom_dir` will still be utilized. The `custom_dir` will only - override/replace files in the parent 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 `custom_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 htmltitle %} -Custom title goes here -{% endblock %} -``` - -In the above example, the `htmltitle` block defined in your custom `main.html` file -will be used in place of the default `htmltitle` 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 `` 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_button`: 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 -explanation of blocks, consult the [Jinja documentation]. - -#### Combining the custom_dir and Template Blocks - -Adding a JavaScript library to the `custom_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() }} - -{% 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 `custom_dir`. The same would be required for -any additional CSS files included in the `custom_dir`. - -[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs -[built-in themes]: #built-in-themes -[Bootstrap]: https://getbootstrap.com/ -[theme configuration options]: ./configuration.md#theme -[Read the Docs]: https://readthedocs.org/ -[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.md#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 -[custom_dir]: ./configuration.md#custom_dir -[name]: ./configuration.md#name -[third party themes]: #third-party-themes -[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks -[base_url]: ./custom-themes.md#base_url -[highlight.js]: https://highlightjs.org/ diff --git a/mkdocs.yml b/mkdocs.yml index f120128f..d7311bca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,13 +15,19 @@ theme: nav: - Home: index.md + - Getting Started: getting-started.md - User Guide: + - Overview: user-guide/index.md + - Installation: user-guide/installation.md - Writing Your Docs: user-guide/writing-your-docs.md - - Styling Your Docs: user-guide/styling-your-docs.md + - Choosing Your Theme: user-guide/choosing-your-theme.md + - Customizing Your Theme: user-guide/customizing-your-theme.md - Configuration: user-guide/configuration.md - Deploying Your Docs: user-guide/deploying-your-docs.md - - Custom Themes: user-guide/custom-themes.md - - Plugins: user-guide/plugins.md + - Developer Guide: + - Overview: dev-guide/index.md + - Themes: dev-guide/themes.md + - Plugins: dev-guide/plugins.md - About: - Release Notes: about/release-notes.md - Contributing: about/contributing.md @@ -44,3 +50,8 @@ google_analytics: ['UA-27795084-5', 'mkdocs.org'] plugins: - search + - redirects: + redirect_maps: + user-guide/plugins.md: dev-guide/plugins.md + user-guide/custom-themes.md: dev-guide/themes.md + user-guide/styling-your-docs.md: user-guide/choosing-your-theme.md diff --git a/requirements/project-min.txt b/requirements/project-min.txt index a66cbdc2..80bc5f54 100644 --- a/requirements/project-min.txt +++ b/requirements/project-min.txt @@ -3,7 +3,8 @@ Jinja2==2.10.1 livereload==2.5.1 Markdown==3.2.1 PyYAML==5.1 -tornado==4.1 +tornado==5.0 mdx_gh_links==0.2 ghp-import==1.0 pyyaml_env_tag==0.1 +mkdocs-redirects==1.0.1 diff --git a/requirements/project.txt b/requirements/project.txt index 3b3201f9..4717212d 100644 --- a/requirements/project.txt +++ b/requirements/project.txt @@ -7,3 +7,4 @@ tornado>=5.1.1 mdx_gh_links>=0.2 ghp-import>=1.0 pyyaml_env_tag>=0.1 +mkdocs-redirects>=1.0.1