theme/README.md

   1 [![PyPI][pypi-image]][pypi-link]
   2
   3   [pypi-image]: https://img.shields.io/pypi/v/mkdocs-windmill.svg
   4   [pypi-link]: https://pypi.python.org/pypi/mkdocs-windmill
   5
   6 # Windmill theme for MkDocs
   7 Outstanding mkdocs theme with a focus on navigation and usability, from Grist Labs.
   8
   9 Highlights:
  10 - Convenient navigation for larger documentation projects.
  11 - Retains state of the navigation menu across page transitions.
  12 - Search with term highlighting.
  13 - User may search in a quick dropdown or load results in a full page.
  14 - Default mkdocs theme within pages, including syntax highlighting.
  15
  16 ## Quick start
  17
  18 To install using `pip`:
  19 ``` sh
  20 pip install mkdocs-windmill
  21 ```
  22
  23 To use in `mkdocs.yml`:
  24 ``` yaml
  25 theme: windmill
  26 ```
  27
  28 Note that it's important for there to exist a homepage, e.g. a top-level root element in mkdocs 1.0+:
  29 ``` yaml
  30 nav:
  31   - Home: index.md
  32 ```
  33
  34 ## Demo and documentation
  35
  36 More details are on this site generated with the Windmill theme:
  37 - [Usage](https://gristlabs.github.io/mkdocs-windmill/#) for more on installation and usage.
  38 - [Customization](https://gristlabs.github.io/mkdocs-windmill/#customization/) for extra configuration options that Windmill supports.
  39
  40 ## Development
  41
  42 If doing development on `mkdocs-windmill`, check it out with
  43 ``` sh
  44 git clone https://github.com/gristlabs/mkdocs-windmill/
  45 cd mkdocs-windmill
  46 ```
  47
  48 There are Selenium browser tests, based on NodeJS. To set them up, first [install Yarn](https://yarnpkg.com/en/docs/install), then from `mkdocs-windmill` checkout, run
  49 ``` sh
  50 cd tests
  51 yarn install
  52 ```
  53
  54 You can run tests when you make changes as follows:
  55 ``` sh
  56 cd tests
  57 MKDOCS_BINARY=<path-to-mkdocs-command> SELENIUM_BROWSER=chrome yarn test
  58 ```