summaryrefslogtreecommitdiffstats
path: root/theme/docs/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'theme/docs/index.md')
-rw-r--r--theme/docs/index.md52
1 files changed, 52 insertions, 0 deletions
diff --git a/theme/docs/index.md b/theme/docs/index.md
new file mode 100644
index 0000000..be1bb25
--- /dev/null
+++ b/theme/docs/index.md
@@ -0,0 +1,52 @@
+# Windmill theme
+
+## About
+
+Windmill theme focuses on clean usable navigation for large documentation
+projects. It retains the state of the menu of pages and folders across page
+transitions, by keeping navigation to an iframe.
+
+It also implements a versatile search, featuring term highlighting, and both a
+quick dropdown and a full-page option that allows the user to come back to
+search results.
+
+Within pages, it uses the default mkdocs theme, including syntax highlighting.
+
+## Installation
+
+Install the Windmill theme using `pip`:
+
+``` sh
+pip install mkdocs-windmill
+```
+
+To install and get started with `mkdocs`, follow [MkDocs documentation](http://www.mkdocs.org/#installation).
+
+## Usage
+
+To use the Windmill theme installed via `pip`, add this to your `mkdocs.yml`:
+
+``` yaml
+theme: 'windmill'
+```
+
+If you cloned Windmill from GitHub:
+
+``` yaml
+theme:
+ name: null
+ custom_dir: '{INSTALL_DIR}/mkdocs_windmill'
+ # Copy settings from mkdocs_theme.yml, which is ignored by custom_dir themes.
+ static_templates: [404.html]
+ search_index_only: true
+ include_search_page: true
+```
+
+Note that it's important for there to exist a homepage, e.g. a top-level root element in mkdocs 1.0+:
+``` yaml
+nav:
+ - Home: index.md
+```
+
+See [Customization](customization.md) for a few extra configuration options
+supported by the Windmill theme.