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.

index.md 9.3KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. +++
  2. title = "Zulma"
  3. description = "A zola theme based off bulma.css"
  4. template = "theme.html"
  5. date = 2019-05-12T22:44:07+01:00
  6. [extra]
  7. created = 2019-07-12T23:55:11+02:00
  8. updated = 2019-05-12T22:44:07+01:00
  9. repository = "https://github.com/Worble/Zulma"
  10. homepage = "https://github.com/Worble/Zulma"
  11. minimum_version = "0.6.0"
  12. license = "MIT"
  13. demo = "https://festive-morse-47d46c.netlify.com/"
  14. [extra.author]
  15. name = "Worble"
  16. homepage = ""
  17. +++
  18. # Zulma
  19. A Bulma theme for Zola. See a live preview [here](https://festive-morse-47d46c.netlify.com/)
  20. ![Zulma Screenshot](/screenshot.png)
  21. ## Contents
  22. - [Zulma](#zulma)
  23. - [Contents](#contents)
  24. - [Installation](#installation)
  25. - [Javascript](#javascript)
  26. - [Sources](#sources)
  27. - [Building](#building)
  28. - [Options](#options)
  29. - [Pagination](#pagination)
  30. - [Taxonomies](#taxonomies)
  31. - [Menu Links](#menu-links)
  32. - [Brand](#brand)
  33. - [Search](#search)
  34. - [Title](#title)
  35. - [Theming](#theming)
  36. - [Original](#original)
  37. - [Known Bugs](#known-bugs)
  38. ## Installation
  39. First download this theme to your `themes` directory:
  40. ```bash
  41. cd themes
  42. git clone https://github.com/Worble/Zulma
  43. ```
  44. and then enable it in your `config.toml`:
  45. ```toml
  46. theme = "zulma"
  47. ```
  48. That's it! No more configuration should be required, however it might look a little basic. Head to the [Options](#options) section to see what you can set for more customizability.
  49. ## Javascript
  50. ### Sources
  51. All the source javascript files live in `javascript/src`. Following is a list of the javascript files, their purpose, and their sources. All files are prefixed with `zulma_` to avoid any name clashes.
  52. - `zulma_search.js` - Used when a user types into the search box on the navbar (if enabled). Taken from [Zola's site](https://github.com/getzola/zola/blob/6100a43/docs/static/search.js).
  53. - `zulma_navbar.js` - Used for the mobile navbar toggle. Taken from the [bulma template](https://github.com/dansup/bulma-templates/blob/6263eb7/js/bulma.js) at Bulmaswatch
  54. - `zulma_switchcss.js` - Used for swapping themes (if enabled).
  55. ### Building
  56. The javascript files are transpiled by babel, minified by webpack, sourcemaps are generated and then everything placed in `static/js`. The repo already contains the transpiled and minified files along with their corrosponding sourcemaps so you don't need to do anything to use these. If you would prefer to build it yourself, feel free to inspect the js files and then run the build process yourself (please ensure that you have [node, npm](https://nodejs.org/en/) and optionally [yarn](https://yarnpkg.com/lang/en/) installed):
  57. ```bash
  58. cd javascript
  59. yarn
  60. yarn webpack
  61. ```
  62. ## Options
  63. ### Pagination
  64. Zulma makes no assumptions about your project. You can freely paginate your content folder or your taxonomies and it will adapt accordingly. For example, editing or creating section (`content/_index.md`) and setting pagination:
  65. ```toml
  66. paginate_by = 5
  67. ```
  68. This is handled internally, no input is needed from the user.
  69. ### Taxonomies
  70. Zulma has 3 taxonomies already set internally: `tags`, `cateogories` and `authors`. Setting of any these three in your config.toml like so:
  71. ```toml
  72. taxonomies = [
  73. {name = "categories"},
  74. {name = "tags", paginate_by = 5, rss = true},
  75. {name = "authors", rss = true},
  76. ]
  77. ```
  78. and setting any of them in a content file:
  79. ```toml
  80. [taxonomies]
  81. categories = ["Hello world"]
  82. tags = ["rust", "ssg", "other", "test"]
  83. authors = ["Joe Bloggs"]
  84. ```
  85. will cause that metadata to appear on the post, either on the header for the name, or at the bottom for tags and categories, and enable those pages.
  86. Making your own taxonomies is also designed to be as easy as possible. First, add it to your cargo.toml
  87. ```toml
  88. taxonomies = [
  89. {name = "links"},
  90. ]
  91. ```
  92. and make the corrosponding folder in your templates, in this case: `templates\links`, and the necessary files: `templates\links\list.html` and `templates\links\single.html`
  93. And then for each, just inherit the taxonomy master page for that page. Before rendering the content block, you may optionally set a variable called `title` for the hero to display on that page, otherwise it will use the default for that taxonomy.
  94. In `single.html`:
  95. ```jinja
  96. {%/* extends "Zulma/templates/taxonomy_single.html" */%}
  97. ```
  98. In `list.html`:
  99. ```jinja
  100. {%/* extends "Zulma/templates/taxonomy_list.html" */%}
  101. {%/* block content */%}
  102. {%/* set title = "These are all the Links"*/%}
  103. {{/* super() */}}
  104. {%/* endblock content */%}
  105. ```
  106. ### Menu Links
  107. In extra, setting `zulma_menu` with a list of items will cause them to render to the top menu bar. It has two paramers, `url` and `name`. These _must_ be set. If you put \$BASE_URL in a url, it will automatically be replaced by the actual site URL. This is the easiest way to allow users to navigate to your taxonomies:
  108. ```toml
  109. [extra]
  110. zulma_menu = [
  111. {url = "$BASE_URL/categories", name = "Categories"},
  112. {url = "$BASE_URL/tags", name = "Tags"},
  113. {url = "$BASE_URL/authors", name = "Authors"}
  114. ]
  115. ```
  116. On mobile, a dropdown burger is rendered using javascript. If the page detects javascript is disabled on the clients machine, it will gracefully degrade to always showing the menu (which isn't pretty, but keeps the site functional).
  117. ### Brand
  118. In extra, setting `zulma_brand` will cause a brand image to display in the upper left of the top menu bar. This link will always lead back to the homepage. It has two parameters, `image`(optional) and `text`(required). `image` will set the brand to an image at the location specified, and `text` will provide the alt text for this image. If you put \$BASE_URL in a url, it will automatically be replaced by the actual site URL. If `image` is not set, the brand will simply be the text specified.
  119. ```toml
  120. [extra]
  121. zulma_brand = {image = "$BASE_URL/images/bulma.png", text = "Home"}
  122. ```
  123. ### Search
  124. Zulma provides search built in. So long as `build_search_index` is set to `true` in `config.toml` then a search input will appear on the top navigation bar. This requires javascript to be enabled to function; if the page detects javascript is disabled on the clients machine, it will hide itself.
  125. The search is shamefully stolen from [Zola's site](https://github.com/getzola/zola/blob/master/docs/static/search.js). Thanks, Vincent!
  126. ### Title
  127. In extra, setting `zulma_title` will set a hero banner on the index page to appear with that title inside.
  128. ```toml
  129. [extra]
  130. zulma_title = "Blog"
  131. ```
  132. If you want to get fancy with it, you can set an image behind using sass like so:
  133. ```scss
  134. .index .hero-body {
  135. background-image: url(https://upload.wikimedia.org/wikipedia/commons/thumb/f/f6/Plum_trees_Kitano_Tenmangu.jpg/1200px-Plum_trees_Kitano_Tenmangu.jpg);
  136. background-position: center;
  137. background-size: cover;
  138. background-repeat: no-repeat;
  139. background-color: rgba(0, 0, 0, 0.6);
  140. background-blend-mode: overlay;
  141. }
  142. ```
  143. This will set the image behind the hero, and darken it so the main text can still be easily read.
  144. ### Theming
  145. In extra, setting `zulma_theme` to a valid value will change the current colour scheme to that one. All themes were taken from [Bulmaswatch](https://jenil.github.io/bulmaswatch/). Valid theme values are:
  146. - default
  147. - darkly
  148. - flatly
  149. - pulse
  150. - simplex
  151. - lux
  152. - slate
  153. - solar
  154. - superhero
  155. All valid themes can also be found under the `extra.zulma_themes` variable in the `theme.toml`. Choosing no theme will set default as the theme. Setting an invalid theme value will cause the site to render improperly.
  156. ```toml
  157. [extra]
  158. zulma_theme = "darkly"
  159. ```
  160. Additionally, in extra, you can also set the `zulma_allow_theme_selection` boolean. Setting this to `true` will allow a menu in the footer to allow users to select their own theme. This option will store their theme choice in their localstorage and apply it on every page, assuming `zulma_allow_theme_selection` is still true. This requires javascript to be enabled to function; if the page detects javascript is disabled on the clients machine, it will hide itself.
  161. Each theme contains the entirety of Bulma, and will weigh in at ~180kb. If you're running on a server severely limited on space, then I'd recommend you delete each theme you're not using, either from the source or from `/public`. Obviously, doing this will cause `zulma_allow_theme_selection` to work improperly, so make sure you either override `extra.zulma_themes` in `config.toml` to only show themes you have left or to not enable this option at all.
  162. ```toml
  163. [extra]
  164. zulma_allow_theme_selection = true
  165. ```
  166. ## Original
  167. This template is based on the [blog template](https://dansup.github.io/bulma-templates/templates/blog.html) over at [Free Bulma Templates](https://dansup.github.io/bulma-templates/). All themes were taken from [Bulmaswatch](https://jenil.github.io/bulmaswatch/). The code behind from originally adapted from the [after-dark](https://github.com/getzola/after-dark/blob/master/README.md) zola template.
  168. ## Known Bugs
  169. - If user theme swapping is enabled and the user selects a theme different to the default, a slight delay will be introduced in page rendering as the css gets swapped out and in by the javascript. This is particularly pronounced when using the dark theme, since it will flash white before going back to black. This is better than the alternative flashes of unstyled content or old theme, but still annoying. I don't know any way around this, but with browser caching it should be fast enough to not cause serious issues.