From ad25b3446096c7f85f14a4160522cb7065295b21 Mon Sep 17 00:00:00 2001 From: Rafael Laverde Date: Wed, 25 Oct 2017 17:22:17 -0500 Subject: [PATCH] Add documentation for themes. --- content/docs/themes/contents.lr | 16 +++ content/docs/themes/creating/contents.lr | 117 ++++++++++++++++++++ content/docs/themes/customizing/contents.lr | 20 ++++ content/docs/themes/installing/contents.lr | 73 ++++++++++++ content/docs/themes/packages/contents.lr | 22 ++++ 5 files changed, 248 insertions(+) create mode 100644 content/docs/themes/contents.lr create mode 100644 content/docs/themes/creating/contents.lr create mode 100644 content/docs/themes/customizing/contents.lr create mode 100644 content/docs/themes/installing/contents.lr create mode 100644 content/docs/themes/packages/contents.lr diff --git a/content/docs/themes/contents.lr b/content/docs/themes/contents.lr new file mode 100644 index 00000000..07f6d2a1 --- /dev/null +++ b/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 considerer +unstable and could change in the future + +Lektor provides a themes system for easy implement, reuse and distibute themes. +Themes are created by the Lektor community, see avalaibles themes [here](/themes) + +Lektor Themes work like an extension of the project, and theme files could be +overrided by project files. diff --git a/content/docs/themes/creating/contents.lr b/content/docs/themes/creating/contents.lr new file mode 100644 index 00000000..5a37f8f6 --- /dev/null +++ b/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 implemeted yet + +You could create a basic empty theme with the following command: + +```bash +$ lektor new theme +``` + +Example: + +```bash +$ lektor new theme demo-theme +``` + + +## Theme components: + +A theme could provide templates, assets, and models (also flowdocks): + +``` +demo-theme +├── assets +├── models +├── templates +└── flowdocks +``` + +## The theme_settings variable + +A `theme_settings` section in `.lektorproject` file could be used for +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. }} +``` +Example: +```jinja +Github + +``` +will output: +``` +Github +``` + +## 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 implemeted yet + +The `lektor_minimum_required_version` is used by Lektor to check the +compatibility when installing a theme. + +## Releasing a theme + +!!!! Not implemeted 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 an screenshot and a thumbnail: + +``` +demo-theme +└── images + ├── thumbnail.png + └── screenshot.png +``` + +Themes added to this lektor-themes repository, will automatically added to the +lektor website. diff --git a/content/docs/themes/customizing/contents.lr b/content/docs/themes/customizing/contents.lr new file mode 100644 index 00000000..7f1cb90b --- /dev/null +++ b/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 overrided some files, for example if a theme +provide a blog model in: + +``` +/themes//models/blog.ini +``` + +You could override it by creating a blog model: + +``` +/models/blog.ini +``` diff --git a/content/docs/themes/installing/contents.lr b/content/docs/themes/installing/contents.lr new file mode 100644 index 00000000..13adfa8f --- /dev/null +++ b/content/docs/themes/installing/contents.lr @@ -0,0 +1,73 @@ +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 distibute by github repos, 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 to only load +a particular theme. + +!!!! Not implemeted 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 support 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`, to have a higher precedence, and files present +in both themes will be loaded from it. + +!! If you don't set `themes` variable, all themes will be loaded, but the order +isn't preserved. diff --git a/content/docs/themes/packages/contents.lr b/content/docs/themes/packages/contents.lr new file mode 100644 index 00000000..ef1c5ccc --- /dev/null +++ b/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 implemeted 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.