Merge pull request #165 from rlaverde/themes-doc

Add documentation for themes.

content/docs/themes/contents.lr

@@ -0,0 +1,16 @@
+title: Themes
+---
+sort_key: 95
+---
+summary: A quick introduction into Lektor Themes.
+---
+body:
+
+!!!! This is under development and isn't released yet. It should be considered
+unstable and could change in the future.
+
+Lektor provides a themes system to easily implement, reuse, and distribute themes.
+This allows you to use assets, templates, models, and / or flowblocks built into the theme.
+Themes are created by the Lektor community.
+
+Lektor themes work like an extension of the project, allowing you to easily adopt features of the theme such as styles, models, or templates.

content/docs/themes/creating/contents.lr

@@ -0,0 +1,117 @@
+title: Creating a Theme
+---
+sort_key: 30
+---
+summary: Explains themes structure and theme.ini file.
+---
+body:
+
+!!!! Not implemented yet.
+
+You could create a basic empty theme with the following command:
+
+```bash
+$ lektor new theme <theme-name>
+```
+
+Example:
+
+```bash
+$ lektor new theme demo-theme
+```
+
+
+## Theme Components:
+
+A theme could provide templates, assets, and models (also flowblocks):
+
+```
+demo-theme
+├── assets
+├── models
+├── templates
+└── flowdocks
+```
+
+## The theme_settings Variable
+
+A `theme_settings` section in `.lektorproject` file could be used to
+parametrize themes:
+
+```ini
+[theme_settings]
+name = "Lektor"
+github_url = "https://github.com/lektor"
+```
+
+And those settings will be accessed in templates through the config env
+variable:
+```jinja
+{{ config.theme_settings.<variable_name> }}
+```
+Example:
+```jinja
+<a href="{{ config.theme_settings.github_url }}">Github</a>
+
+```
+will output:
+```
+<a href="https://github.com/lektor/lektor">Github</a>
+```
+
+## The theme.ini File
+
+Themes could provide a `theme.ini` file, that is optional, but it's required if
+you want to add your theme to the lektor community themes.
+
+Example:
+
+```ini
+name = "Demo theme"
+license = "MIT"
+licenselink = "https://github.com/lektor/lektor-demo-theme/blob/master/LICENSE.md"
+description = "Simple, minimal theme for Lektor "
+homepage = "https://github.com/lektor/lektor-demo-theme"
+tags = "simple,minimal,demo"
+features = "blog"
+lektor_minimum_required_version = 3.1
+
+[author]
+name = "lektor"
+homepage = "http://getlektor.com/"
+
+[original]
+author = ""
+homepage = ""
+repo = ""
+
+[packages]
+lektor-disqus-comments = 0.2
+```
+
+The `[original]` section is only required if you are porting an existing theme.
+
+!!!! Not implemented yet
+
+The `lektor_minimum_required_version` is used by Lektor to check the
+compatibility when installing a theme.
+
+## Releasing a Theme
+
+!!!! Not implemented yet
+
+You could add a theme to Lektor community theme, open a pull request against
+(lektor themes)[https://github.com/lektor/lektor-themes] adding it as a git
+submodule.
+
+You should also include an `images/` folder with a screenshot and a thumbnail:
+
+```
+demo-theme
+└──  images
+    ├── thumbnail.png
+    └── screenshot.png
+```
+
+Themes added to this lektor-themes repository, will automatically be added to the
+lektor website.

content/docs/themes/customizing/contents.lr

@@ -0,0 +1,20 @@
+title: Customizing a Theme
+---
+sort_key: 20
+---
+summary: Explains how models, templates, or assets could be overrided.
+---
+body:
+
+You could personalize a theme by overriding files, for example if a theme
+provides a blog model in:
+
+```
+/themes/<theme>/models/blog.ini
+```
+
+You could override it by creating a blog model:
+
+```
+/models/blog.ini
+```

content/docs/themes/installing/contents.lr

@@ -0,0 +1,74 @@
+title: Installing a Theme
+---
+sort_key: 10
+---
+summary: Explains how to install Lektor themes.
+---
+body:
+
+For installing a theme you just need to copy it to the `themes/` folder
+
+```
+project
+├── assets
+├── models
+├── content
+...
+└── themes
+    └── lektor-theme-nix
+```
+
+Themes are normally distributed by public Git repositories, so you could install a theme by
+cloning the repo:
+
+```bash
+cd themes
+git clone URL_TO_THEME_REPO
+```
+
+For example, for installing `lektor-theme-nix`:
+```bash
+cd themes
+git clone https://github.com/rlaverde/lektor-theme-nix.git
+```
+
+If you download several themes, setting `themes` variable will allow you to only load
+a particular theme.
+
+!!!! Not implemented yet.
+
+You could add the `themes` variable to the `.lektorproject` file and Lektor will
+search in the (community themes)[/themes] and automatically install it.
+
+```ini
+[project]
+themes = lextor-theme-nix
+```
+
+## Installing Multiple Themes
+
+Lektor also supports installing several themes. Copy them to the `themes/`
+folder, and set the `themes` variable to indicate the precedence (optional).
+
+```
+project
+├── assets
+├── models
+├── content
+...
+└── themes
+    ├── lektor-theme-other-theme/
+    └── lektor-theme-nix/
+```
+
+```ini
+[project]
+themes = lextor-theme-nix, lektor-theme-other-theme
+```
+
+This will make `lektor-theme-nix`, because it's listed first, have a higher precedence.
+Files present in multiple themes will be loaded from right to left, so that the first (left-most)
+theme is preferred over the theme(s) to its right.
+
+!! If you don't set the `themes` variable, all themes will be loaded, but the order
+isn't preserved.

content/docs/themes/packages/contents.lr

@@ -0,0 +1,22 @@
+title: Installing Plugins with a Theme.
+---
+sort_key: 40
+---
+summary: Explains how a theme could depend or include several plugins.
+---
+body:
+
+!!!! Not implemented yet.
+
+Themes could depend on [plugins](../../plugins), and they will be loaded along
+the theme.
+
+1. You could use the `[packages]` section of the `theme.ini` to install
+released packages:
+```ini
+[packages]
+lektor-disqus-comments = 0.2
+```
+
+2. Plugins can be added to the `packages/` folder in the theme. Each plugin has
+to go into a separate folder.