From 835c27b5b2c3f6c079de6c556b2d532bf3d95351 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Sat, 25 Apr 2015 10:03:47 +0100 Subject: [PATCH] Add details about implementing search in a custom theme --- docs/css/extra.css | 3 ++ docs/user-guide/styling-your-docs.md | 43 ++++++++++++++++++++++++++-- mkdocs.yml | 1 + mkdocs/themes/mkdocs/css/base.css | 33 +++++++++++++++++++++ 4 files changed, 78 insertions(+), 2 deletions(-) diff --git a/docs/css/extra.css b/docs/css/extra.css index 44ceea16..c1b6d587 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -8,6 +8,9 @@ div.col-md-9 p:first-of-type { text-align: center; } +div.col-md-9 p.admonition-title:first-of-type { + text-align: left; +} div.col-md-9 h1:first-of-type .headerlink { display: none; diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 6c3f5041..7c482a7f 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/docs/user-guide/styling-your-docs.md @@ -86,7 +86,7 @@ To create a new custom theme or more heavily customise an existing theme, see th ## Custom themes -The bare minimum required for a custom theme is a `base.html` 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: +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/ @@ -102,6 +102,8 @@ You would include the following setting to use the custom theme directory: 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: @@ -113,4 +115,41 @@ The simplest `base.html` file is the following: -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](https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes) and modify it accordingly. +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. + + + + +### 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 documentations 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. +
+ +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/ diff --git a/mkdocs.yml b/mkdocs.yml index bd081ec2..18e3853f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,7 @@ pages: markdown_extensions: toc: permalink: "" + admonition: copyright: Copyright © 2014, Tom Christie. google_analytics: ['UA-27795084-5', 'mkdocs.org'] diff --git a/mkdocs/themes/mkdocs/css/base.css b/mkdocs/themes/mkdocs/css/base.css index b4051e34..3a31ef73 100644 --- a/mkdocs/themes/mkdocs/css/base.css +++ b/mkdocs/themes/mkdocs/css/base.css @@ -191,3 +191,36 @@ footer { h1:hover .headerlink, h2:hover .headerlink, h3:hover .headerlink, h4:hover .headerlink, h5:hover .headerlink, h6:hover .headerlink{ display:inline-block; } + + + +.admonition { + padding: 15px; + margin-bottom: 20px; + border: 1px solid transparent; + border-radius: 4px; + text-align: left; +} + +.admonition.note { + color: #3a87ad; + background-color: #d9edf7; + border-color: #bce8f1; +} + +.admonition.warning { + color: #c09853; + background-color: #fcf8e3; + border-color: #fbeed5; +} + +.admonition.danger { + color: #b94a48; + background-color: #f2dede; + border-color: #eed3d7; +} + +.admonition-title { + font-weight: bold; + text-align: left; +}