zola/docs/content/documentation/themes/creating-a-theme.md

78 lines
2.6 KiB
Markdown
Raw Normal View History

2017-10-01 03:51:43 +00:00
+++
title = "Creating a theme"
weight = 30
+++
Creating a theme is exactly like creating a normal site with Zola, except you
will want to use many [Tera blocks](https://tera.netlify.com/docs#inheritance) to
2017-10-01 03:51:43 +00:00
allow users to easily modify it.
2018-02-28 19:44:30 +00:00
## Getting started
As mentioned, a theme is just like any site; start by running `zola init MY_THEME_NAME`.
2018-02-28 19:44:30 +00:00
The only thing needed to turn that site into a theme is to add a `theme.toml` configuration file with the
2018-02-28 19:44:30 +00:00
following fields:
2017-10-01 03:51:43 +00:00
```toml
2018-02-28 19:44:30 +00:00
name = "my theme name"
2017-10-01 03:51:43 +00:00
description = "A classic blog theme"
license = "MIT"
2018-10-18 21:09:32 +00:00
homepage = "https://github.com/Keats/zola-hyde"
# The minimum version of Zola required
2018-08-04 11:15:01 +00:00
min_version = "0.4.0"
# An optional live demo URL
demo = ""
2017-10-01 03:51:43 +00:00
# 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
2018-10-18 21:09:32 +00:00
# Use snake_casing to be consistent with the rest of Zola
2017-10-01 03:51:43 +00:00
[extra]
# The theme author info: you!
[author]
name = "Vincent Prouillet"
homepage = "https://vincent.is"
# If this is porting a theme from another static site engine, provide
# the info of the original author here
[original]
author = "mdo"
homepage = "http://markdotto.com/"
repo = "https://www.github.com/mdo/hyde"
```
A simple theme you can use as an example is [Hyde](https://github.com/Keats/hyde).
2018-02-28 19:44:30 +00:00
## Working on a theme
2018-10-18 21:09:32 +00:00
As a theme is just a site, you can simply use `zola serve` and make changes to your
theme, with live reload working as expected.
2018-02-28 19:44:30 +00:00
Make sure to commit every directory (including `content`) in order for other people
2018-02-28 19:44:30 +00:00
to be able to build the theme from your repository.
2017-10-01 03:51:43 +00:00
2018-02-28 19:44:30 +00:00
### Caveat
2017-10-01 03:51:43 +00:00
Please note that [include paths](https://tera.netlify.com/docs#include) can only be used in normal templates.
Theme templates should use [macros](https://tera.netlify.com/docs#macros) instead.
2017-10-24 17:32:26 +00:00
2018-02-28 19:44:30 +00:00
## Submitting a theme to the gallery
If you want your theme to be featured in the [themes](@/themes/_index.md) section
2018-02-28 19:44:30 +00:00
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
2017-10-24 17:32:26 +00:00
- `README.md`: a thorough README explaining how to use the theme and any other information
of importance
The first step is to make sure that the theme meets the following three requirements:
2018-02-28 19:44:30 +00:00
- 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
2018-10-18 21:09:32 +00:00
When your theme is ready, you can submit it to the [themes repository](https://github.com/getzola/themes)
2018-02-28 19:44:30 +00:00
by following the process in the README.