You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

creating-a-theme.md 2.7KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677
  1. +++
  2. title = "Creating a theme"
  3. weight = 30
  4. +++
  5. Creating a theme is exactly like creating a normal site with Zola, except you
  6. will want to use many [Tera blocks](https://tera.netlify.com/docs/templates/#inheritance) to
  7. allow users to easily modify it.
  8. ## Getting started
  9. As mentioned, a theme is just like any site: start with running `zola init MY_THEME_NAME`.
  10. The only thing needed to turn that site into a theme is to add `theme.toml` configuration file with the
  11. following fields:
  12. ```toml
  13. name = "my theme name"
  14. description = "A classic blog theme"
  15. license = "MIT"
  16. homepage = "https://github.com/Keats/zola-hyde"
  17. # The minimum version of Zola required
  18. min_version = "0.4.0"
  19. # An optional live demo URL
  20. demo = ""
  21. # Any variable there can be overriden in the end user `config.toml`
  22. # You don't need to prefix variables by the theme name but as this will
  23. # be merged with user data, some kind of prefix or nesting is preferable
  24. # Use snake_casing to be consistent with the rest of Zola
  25. [extra]
  26. # The theme author info: you!
  27. [author]
  28. name = "Vincent Prouillet"
  29. homepage = "https://vincent.is"
  30. # If this is porting a theme from another static site engine, provide
  31. # the info of the original author here
  32. [original]
  33. author = "mdo"
  34. homepage = "http://markdotto.com/"
  35. repo = "https://www.github.com/mdo/hyde"
  36. ```
  37. A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde).
  38. ## Working on a theme
  39. As a theme is just a site, you can simply use `zola serve` and make changes to your
  40. theme, with live reloading working as expected.
  41. Make sure to commit every directory (including `content`) in order for other people
  42. to be able to build the theme from your repository.
  43. ### Caveat
  44. Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in normal templates.
  45. Theme templates should use [macros](https://tera.netlify.com/docs/templates/#macros) instead.
  46. ## Submitting a theme to the gallery
  47. If you want your theme to be featured in the [themes](@/themes/_index.md) section
  48. of this site, the theme will require two more things:
  49. - `screenshot.png`: a screenshot of the theme in action with a max size of around 2000x1000
  50. - `README.md`: a thorough README explaining how to use the theme and any other information
  51. of importance
  52. The first step is to make sure the theme is fulfilling those three requirements:
  53. - have a `screenshot.png` of the theme in action with a max size of around 2000x1000
  54. - have a thorough `README.md` explaining how to use the theme and any other information
  55. of importance
  56. - be of reasonably high quality
  57. When your theme is ready, you can submit it to the [themes repository](https://github.com/getzola/themes)
  58. by following the process in the README.