From ad25b3446096c7f85f14a4160522cb7065295b21 Mon Sep 17 00:00:00 2001 From: Rafael Laverde Date: Wed, 25 Oct 2017 17:22:17 -0500 Subject: [PATCH 1/9] 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. From 724525623f52be80d42b3a3f59a0fae8af848686 Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 14:27:04 -0600 Subject: [PATCH 2/9] Updating text in main theme docs page Added a little info and tweaks. --- content/docs/themes/contents.lr | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/docs/themes/contents.lr b/content/docs/themes/contents.lr index 07f6d2a1..33b93e0c 100644 --- a/content/docs/themes/contents.lr +++ b/content/docs/themes/contents.lr @@ -6,11 +6,11 @@ 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 +!!!! 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 for easy implement, reuse and distibute themes. -Themes are created by the Lektor community, see avalaibles themes [here](/themes) +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. See available themes [here](/themes). -Lektor Themes work like an extension of the project, and theme files could be -overrided by project files. +Lektor Themes work like an extension of the project, allowing you to easily adopt features of the theme such as styles, models, or templates. Theme files are loaded first, and any conflicting project files override the theme, allowing for customization. From 1b358cf3f7199032dbcd103c93b09642a182b37b Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 16:50:06 -0600 Subject: [PATCH 3/9] Tweaks and more info on themes installation --- content/docs/themes/installing/contents.lr | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/content/docs/themes/installing/contents.lr b/content/docs/themes/installing/contents.lr index 13adfa8f..4728af80 100644 --- a/content/docs/themes/installing/contents.lr +++ b/content/docs/themes/installing/contents.lr @@ -18,7 +18,7 @@ project └── lektor-theme-nix ``` -Themes are normally distibute by github repos, so you could install a theme by +Themes are normally distributed by public Git repositories, so you could install a theme by cloning the repo: ```bash @@ -32,12 +32,12 @@ 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 +If you download several themes, setting `themes` variable will allow you to only load a particular theme. -!!!! Not implemeted yet. +!!!! Not implemented yet. -You could add the `themes` variable to the `.lektorproject` file and lektor will +You could add the `themes` variable to the `.lektorproject` file and Lektor will search in the (community themes)[/themes] and automatically install it. ```ini @@ -47,7 +47,7 @@ themes = lextor-theme-nix ## Installing multiple themes -Lektor also support installing several themes, copy them to the `themes/` +Lektor also supports installing several themes. Copy them to the `themes/` folder, and set the `themes` variable to indicate the precedence (optional). ``` @@ -63,11 +63,12 @@ project ```ini [project] -themes = lextor-theme-nix,lektor-theme-other-theme +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. +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 `themes` variable, all themes will be loaded, but the order +!! If you don't set the `themes` variable, all themes will be loaded, but the order isn't preserved. From 8f8c0271a1862a03b928269f11129383472839dd Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 16:53:29 -0600 Subject: [PATCH 4/9] Capitalizing title --- content/docs/themes/installing/contents.lr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/themes/installing/contents.lr b/content/docs/themes/installing/contents.lr index 4728af80..be45c200 100644 --- a/content/docs/themes/installing/contents.lr +++ b/content/docs/themes/installing/contents.lr @@ -1,4 +1,4 @@ -title: Installing a theme +title: Installing a Theme --- sort_key: 10 --- From ae41c217ffc63964a24f9c8b4feb0250850f3f24 Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 16:56:35 -0600 Subject: [PATCH 5/9] Tweaks to customizing themes page --- content/docs/themes/customizing/contents.lr | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/themes/customizing/contents.lr b/content/docs/themes/customizing/contents.lr index 7f1cb90b..7ec64986 100644 --- a/content/docs/themes/customizing/contents.lr +++ b/content/docs/themes/customizing/contents.lr @@ -1,4 +1,4 @@ -title: Customizing a theme +title: Customizing a Theme --- sort_key: 20 --- @@ -6,8 +6,8 @@ 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: +You could personalize a theme by overriding files, for example if a theme +provides a blog model in: ``` /themes//models/blog.ini From 0cd18e7b5e9b0d80d3f6b4c894554e794c0c1e09 Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 17:11:59 -0600 Subject: [PATCH 6/9] Tweaks to Theme Creating --- content/docs/themes/creating/contents.lr | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/content/docs/themes/creating/contents.lr b/content/docs/themes/creating/contents.lr index 5a37f8f6..17f7a5c3 100644 --- a/content/docs/themes/creating/contents.lr +++ b/content/docs/themes/creating/contents.lr @@ -6,7 +6,7 @@ summary: Explains themes structure and theme.ini file. --- body: -!!!! Not implemeted yet +!!!! Not implemented yet. You could create a basic empty theme with the following command: @@ -21,9 +21,9 @@ $ lektor new theme demo-theme ``` -## Theme components: +## Theme Components: -A theme could provide templates, assets, and models (also flowdocks): +A theme could provide templates, assets, and models (also flowblocks): ``` demo-theme @@ -33,9 +33,9 @@ demo-theme └── flowdocks ``` -## The theme_settings variable +## The theme_settings Variable -A `theme_settings` section in `.lektorproject` file could be used for +A `theme_settings` section in `.lektorproject` file could be used to parametrize themes: ```ini @@ -59,7 +59,7 @@ will output: Github ``` -## The theme.ini file +## 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. @@ -91,20 +91,20 @@ lektor-disqus-comments = 0.2 The `[original]` section is only required if you are porting an existing theme. -!!!! Not implemeted yet +!!!! Not implemented yet The `lektor_minimum_required_version` is used by Lektor to check the compatibility when installing a theme. -## Releasing a theme +## Releasing a Theme -!!!! Not implemeted yet +!!!! Not implemented yet -You could add a theme to lektor community theme, open a pull request against +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: +You should also include an `images/` folder with a screenshot and a thumbnail: ``` demo-theme @@ -113,5 +113,5 @@ demo-theme └── screenshot.png ``` -Themes added to this lektor-themes repository, will automatically added to the +Themes added to this lektor-themes repository, will automatically be added to the lektor website. From 6d5a0e0c0173be4b730f06685fb3b946278a5b79 Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 17:15:45 -0600 Subject: [PATCH 7/9] Tweaks to themes packages --- content/docs/themes/packages/contents.lr | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/themes/packages/contents.lr b/content/docs/themes/packages/contents.lr index ef1c5ccc..02f61b7a 100644 --- a/content/docs/themes/packages/contents.lr +++ b/content/docs/themes/packages/contents.lr @@ -1,4 +1,4 @@ -title: Installing plugins with a theme. +title: Installing Plugins with a Theme. --- sort_key: 40 --- @@ -6,7 +6,7 @@ summary: Explains how a theme could depend or include several plugins. --- body: -!!!! Not implemeted yet. +!!!! Not implemented yet. Themes could depend on [plugins](../../plugins), and they will be loaded along the theme. From c61ce28a4efb2274e268307e7574013d5599ce3b Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 17:25:46 -0600 Subject: [PATCH 8/9] Further content tweaks to main themes page --- content/docs/themes/contents.lr | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/themes/contents.lr b/content/docs/themes/contents.lr index 33b93e0c..1e0e668d 100644 --- a/content/docs/themes/contents.lr +++ b/content/docs/themes/contents.lr @@ -11,6 +11,6 @@ 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. See available themes [here](/themes). +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. Theme files are loaded first, and any conflicting project files override the theme, allowing for customization. +Lektor themes work like an extension of the project, allowing you to easily adopt features of the theme such as styles, models, or templates. From b98ef6c9ff40a156d8b5d62763e5581bcaba2da5 Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Thu, 11 Jan 2018 17:28:04 -0600 Subject: [PATCH 9/9] Capitalizing a subtitle --- content/docs/themes/installing/contents.lr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/themes/installing/contents.lr b/content/docs/themes/installing/contents.lr index be45c200..a9212e06 100644 --- a/content/docs/themes/installing/contents.lr +++ b/content/docs/themes/installing/contents.lr @@ -45,7 +45,7 @@ search in the (community themes)[/themes] and automatically install it. themes = lextor-theme-nix ``` -## Installing multiple themes +## 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).