From 6c09c8ba8beefbf4c2d55fea978ada2057b06ed3 Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Wed, 28 Feb 2018 20:44:30 +0100 Subject: [PATCH] Slight tweak on theme docs --- .../documentation/themes/creating-a-theme.md | 51 +++++++++++-------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/content/documentation/themes/creating-a-theme.md b/docs/content/documentation/themes/creating-a-theme.md index 6b1d2f3f..b45da732 100644 --- a/docs/content/documentation/themes/creating-a-theme.md +++ b/docs/content/documentation/themes/creating-a-theme.md @@ -7,29 +7,25 @@ Creating is exactly like creating a normal site with Gutenberg, except you will want to use many [Tera blocks](https://tera.netlify.com/docs/templates/#inheritance) to allow users to easily modify it. -A theme also need to have a `theme.toml` configuration file with the -following fields, here's the one from a [real template](https://github.com/Keats/hyde): +## Getting started +As mentioned, a theme is just like any site: start with running `gutenberg init MY_THEME_NAME`. + +The only thing needed to turn that site into a theme is to add `theme.toml` configuration file with the +following fields: ```toml -name = "hyde" +name = "my theme name" description = "A classic blog theme" license = "MIT" homepage = "https://github.com/Keats/gutenberg-hyde" # The minimum version of Gutenberg required -min_version = "0.1" +min_version = "0.3" # Any variable there can be overriden in the end user `config.toml` # You don't need to prefix variables by the theme name but as this will # be merged with user data, some kind of prefix or nesting is preferable # Use snake_casing to be consistent with the rest of Gutenberg [extra] -hyde_sticky = true -hyde_reverse = false -hyde_theme = "" -hyde_links = [ - {url = "https://google.com", name = "Google.com"}, - {url = "https://google.fr", name = "Google.fr"}, -] # The theme author info: you! [author] @@ -44,21 +40,36 @@ homepage = "http://markdotto.com/" repo = "https://www.github.com/mdo/hyde" ``` -A theme will also need three directories to work: +A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde). -- `static`: any static files used in this theme -- `templates`: all templates used in this theme -- `sass`: Sass stylesheets for this theme, can be empty +## Working on a theme +As a theme is just a site, you can simply use `gutenberg serve` and make changes to your +theme, with live reloading working as expected. -To be featured on this site, the theme will require two more things: +Make sure to commit every directory (including `content`) in order for other people +to be able to build the theme from your repository. -- `screenshot.png`: a screenshot of the theme in action, its size needs to be reasonable +### Caveat + +Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in used in normal templates. +Theme templates should use [macros](https://tera.netlify.com/docs/templates/#macros) instead. + +## Submitting a theme to the gallery + +If you want your theme to be featured in the [themes](./content/themes/_index.md) section +of this site, the theme will require two more things: + +- `screenshot.png`: a screenshot of the theme in action with a max size of around 2000x1000 - `README.md`: a thorough README explaining how to use the theme and any other information of importance -A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde). +The first step is to make sure the theme is fulfilling those three requirements: -# Caveat +- have a `screenshot.png` of the theme in action with a max size of around 2000x1000 +- have a thorough `README.md` explaining how to use the theme and any other information +of importance +- be of reasonably high quality -Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in used in normal templates. Theme templates should use [macro's](https://tera.netlify.com/docs/templates/#macros) instead. +When your theme is ready, you can submit it to the [themes repository](https://github.com/Keats/gutenberg-themes) +by following the process in the README.