theme/docs/index.md

   1 # Windmill theme
   2
   3 ## About
   4
   5 Windmill theme focuses on clean usable navigation for large documentation
   6 projects. It retains the state of the menu of pages and folders across page
   7 transitions, by keeping navigation to an iframe.
   8
   9 It also implements a versatile search, featuring term highlighting, and both a
  10 quick dropdown and a full-page option that allows the user to come back to
  11 search results.
  12
  13 Within pages, it uses the default mkdocs theme, including syntax highlighting.
  14
  15 ## Installation
  16
  17 Install the Windmill theme using `pip`:
  18
  19 ``` sh
  20 pip install mkdocs-windmill
  21 ```
  22
  23 To install and get started with `mkdocs`, follow [MkDocs documentation](http://www.mkdocs.org/#installation).
  24
  25 ## Usage
  26
  27 To use the Windmill theme installed via `pip`, add this to your `mkdocs.yml`:
  28
  29 ``` yaml
  30 theme: 'windmill'
  31 ```
  32
  33 If you cloned Windmill from GitHub:
  34
  35 ``` yaml
  36 theme:
  37   name: null
  38   custom_dir: '{INSTALL_DIR}/mkdocs_windmill'
  39   # Copy settings from mkdocs_theme.yml, which is ignored by custom_dir themes.
  40   static_templates: [404.html]
  41   search_index_only: true
  42   include_search_page: true
  43 ```
  44
  45 Note that it's important for there to exist a homepage, e.g. a top-level root element in mkdocs 1.0+:
  46 ``` yaml
  47 nav:
  48   - Home: index.md
  49 ```
  50
  51 See [Customization](customization.md) for a few extra configuration options
  52 supported by the Windmill theme.