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.

README.md 15KB

7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. # Gutenberg
  2. [![Build Status](https://travis-ci.org/Keats/gutenberg.svg?branch=master)](https://travis-ci.org/Keats/gutenberg)
  3. [![Build status](https://ci.appveyor.com/api/projects/status/h4t9r6h5gom839q0/branch/master?svg=true)](https://ci.appveyor.com/project/Keats/gutenberg/branch/master)
  4. [![Chat](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/gutenberg-rs/Lobby#)
  5. An opinionated static site generator written in Rust.
  6. ## Installation
  7. You can get the latest release by going to the [Release page](https://github.com/Keats/gutenberg/releases).
  8. ## Usage
  9. ### Creating a new site
  10. Use `gutenberg init <a_directory_name>`.
  11. This will create a folder with the name given and the base structure of a gutenberg site.
  12. ### Working on a site
  13. Use `gutenberg serve` to spin up a server that will automatically live reload any changes to the
  14. content, templates or static files.
  15. ### Building a site
  16. Use `gutenberg build` to generate the site in the `public/` directory.
  17. ### Gutenberg terms
  18. Some words are going to be repeated in the docs so let's make sure they are clear.
  19. - Page: a markdown file in the `content` directory that has a name different from `_index.md`
  20. - Section: a group of pages in the `content` directory that has `_index.md` in the same folder
  21. ### Configuration
  22. Configuration is using the [TOML](https://github.com/toml-lang/toml) language.
  23. Only 2 parameters are required: `title` and `base_url`.
  24. The other options are:
  25. - `highlight_code`: Whether to highlight all code blocks found in markdown files. Defaults to false
  26. - `highlight_theme`: Which themes to use for code highlighting. Defaults to "base16-ocean-dark"
  27. - `language_code`: The language used in the site. Defaults to "en"
  28. - `generate_rss`: Whether to generate RSS, defaults to false
  29. - `generate_tags_pages`: Whether to generate tags and individual tag pages if some pages have them. Defaults to true
  30. - `generate_categories_pages`: Whether to generate categories and individual category categories if some pages have them. Defaults to true
  31. - `compile_sass`: Whether to compile all `.scss` files in the `sass` directory
  32. If you want to add some of your own variables, you will need to put them in the `[extra]` table in `config.toml` or
  33. they will be silently ignored.
  34. ### Templates
  35. Templates live in the `templates/` directory and the files need to end by `.html`.
  36. Only [Tera](https://github.com/Keats/tera) templates are supported.
  37. Each kind of page get their own variables:
  38. // TODO: detail the schema of the variables
  39. - index.html: gets `section` representing the index section
  40. - page.html: gets `page` that contains the data for that page
  41. - section.html: gets `section` that contains the data for pages in it and its subsections
  42. - tags.html: gets `tags`
  43. - tag.html: gets `tag` and `pages`
  44. - categories.html: gets `categories`
  45. - category.html: gets `category` and `pages`
  46. Additionally, all pages get a `config` variable representing the data in `config.toml`, `current_url` that represent
  47. the absolute URL of the current page and `current_path` that represents the path of the URL of the current page, starting with `/`.
  48. If you want to know all the data present in a template content, simply put `{{ __tera_context }}`
  49. in the templates and it will print it.
  50. Gutenberg also ships with a few Tera global functions:
  51. #### `get_page`
  52. Takes a path to a `.md` file and returns the associated page
  53. ```jinja2
  54. {% set page = get_page(path="blog/page2.md") %}
  55. ```
  56. #### `get_section`
  57. Takes a path to a `_index.md` file and returns the associated section
  58. ```jinja2
  59. {% set section = get_section(path="blog/_index.md") %}
  60. ```
  61. #### `get_url`
  62. Gets the permalink for the given path.
  63. If the path starts with `./`, it will be understood as an internal
  64. link like the ones used in markdown.
  65. ```jinja2
  66. {% set url = get_url(path="./blog/_index.md") %}
  67. ```
  68. This can also be used to get the permalinks for static assets for example if
  69. we want to link to the file that is located at `static/css/app.css`:
  70. ```jinja2
  71. {{ get_url(path="css/app.css") }}
  72. ```
  73. Note that the path shouldn't start with a slash.
  74. In the case of non-internal links, you can also add a cachebust of the format `?t=1290192` at the end of a URL
  75. by passing `cachebust=true` to the `get_url` function.
  76. ### Static files
  77. Everything in the `static` folder will be copied into the output directory as-is.
  78. ### Pages
  79. Pages have to start with a front-matter enclosed in `+++`. Here is a minimal example:
  80. ```md
  81. +++
  82. title = "My page"
  83. description = "Some meta info"
  84. +++
  85. A simple page with fixed url
  86. ```
  87. A front-matter has only optional variables:
  88. - title
  89. - description
  90. - date: a YYYY-MM-DD or RFC339 formatted date
  91. - slug: what slug to use in the url
  92. - url: this overrides the slug and make this page accessible at `{config.base_url}/{url}`
  93. - tags: an array of strings
  94. - category: only one category is allowed
  95. - draft: whether the post is a draft or not
  96. - template: if you want to change the template used to render that specific page
  97. - aliases: which URL to redirect to the new: useful when you changed a page URL and don't want to 404
  98. Even if your front-matter is empty, you will need to put the `+++`.
  99. You can also, like in the config, add your own variables in a `[extra]` table.
  100. The front-matter will be accessible in templates at the `page.meta` field.
  101. By default, the URL of a page will follow the filesystem paths. For example, if you have
  102. a page at `content/posts/python3.md`, it will be available at `{config.base_url}/posts/python3/`.
  103. You can override the slug created from the filename by setting the `slug` variable in the front-matter.
  104. Quite often, a page will have assets and you might want to co-locate them with the markdown file.
  105. Gutenberg supports that pattern out of the box: you can create a folder, put a file named `index.md` and any number of files
  106. along with it that are NOT markdown.
  107. Those assets will be copied in the same folder when building so you can just use a relative path to use them.
  108. A summary is only defined if you put `<!-- more -->` in the content. If present in a page, the summary will be from
  109. the start up to that tag.
  110. ### Sections
  111. Sections represent a group of pages, for example a `tutorials` section of your site.
  112. Sections are only created in Gutenberg when a file named `_index.md` is found in the `content` directory.
  113. This `_index.md` file needs to include a front-matter as well, but won't have content:
  114. ```md
  115. +++
  116. title = "Tutorials"
  117. +++
  118. ```
  119. You can also set the `template` variable to change which template will be used to render that section.
  120. Sections will also automatically pick up their subsections, allowing you to make some complex pages layout and
  121. table of contents.
  122. You can define how a section pages are sorted using the `sort_by` key in the front-matter. The choices are `date`, `order`, `weight` (opposite of order)
  123. and `none` (default). Pages that can't be sorted will currently be silently dropped: the final page will be rendered but it will not appear in
  124. the `pages` variable in the section template.
  125. A special case is the `_index.md` at the root of the `content` directory which represents the homepage. It is only there
  126. to control pagination and sorting of the homepage.
  127. You can also paginate section, including the index by setting the `paginate_by` field in the front matter to an integer.
  128. This represents the number of pages for each pager of the paginator.
  129. You will need to access pages through the `paginator` object. (TODO: document that).
  130. You can redirect a root section page to another url by using the `redirect_to` parameter of the front-matter followed
  131. by a path:
  132. ```
  133. redirect_to = "docs/docker"
  134. ```
  135. ### Table of contents
  136. Each page/section will generate a table of content based on the title. It is accessible through `section.toc` and
  137. `page.toc`. It is a list of headers that contains a `permalink`, a `title` and `children`.
  138. Here is an example on how to make a ToC using that:
  139. ```jinja2
  140. <ul>
  141. {% for h1 in page.toc %}
  142. <li>
  143. <a href="{{h1.permalink | safe}}">{{ h1.title }}</a>
  144. {% if h1.children %}
  145. <ul>
  146. {% for h2 in h1.children %}
  147. <li>
  148. <a href="{{h2.permalink | safe}}">{{ h2.title }}</a>
  149. </li>
  150. {% endfor %}
  151. </ul>
  152. {% endif %}
  153. </li>
  154. {% endfor %}
  155. </ul>
  156. ```
  157. While headers are neatly ordered in that example, you can a table of contents looking like h2, h2, h1, h3 without
  158. any issues.
  159. ### Taxonomies: tags and categories
  160. Individual tag/category pages are only supported for pages having a date.
  161. ### Sass compilation
  162. You can automatically compile and watch all `.scss` files by adding `compile_sass = true` in your
  163. `config.toml`.
  164. ### Theme
  165. Gutenberg has built-in support for themes.
  166. To use a theme, download the theme in the `themes` folder and add its name in your `config.toml`:
  167. ```toml
  168. // if the theme is called hyde and found in themes/hyde
  169. theme = "hyde"
  170. ```
  171. Themes can provide values in the `extra` portion of the `theme.toml` but you can override any
  172. of those in the `config.toml`.
  173. Changes in the themes folder are not watched: if you want to make changes to a theme, it's better
  174. to extend a template in your own `templates` directory or create a new Sass file in the `sass` directory.
  175. You get to be able to update the themes easily that way.
  176. #### List of themes
  177. - hyde: https://github.com/Keats/hyde
  178. #### Making a theme
  179. See https://github.com/Keats/hyde for an example on how to build a theme.
  180. The most important thing to remember is that you cannot use Tera's `include` in a theme, which means adding `block`
  181. everywhere a user might want to customise things: `extra_head` to add some JS/CSS files for example.
  182. ### Code highlighting themes
  183. Code highlighting can be turned on by setting `highlight_code = true` in `config.toml`.
  184. When turned on, all text between backticks will be highlighted, like the example below.
  185. ```rust
  186. let site = Site::new();
  187. ```
  188. If the name of the language is not given, it will default to plain-text highlighting.
  189. Gutenberg uses Sublime Text themes for syntax highlighting. It comes with the following theme
  190. built-in:
  191. - base16-ocean-dark
  192. - base16-ocean-light
  193. - gruvbox-dark
  194. - gruvbox-light
  195. - inspired-github
  196. - kronuz
  197. - material-dark
  198. - material-light
  199. - monokai
  200. - solarized-dark
  201. - solarized-light
  202. ### Internal links
  203. You can have internal links in your markdown that will be replaced with the full URL when rendering.
  204. To do so, use the normal markdown link syntax, start the link with `./` and point to the `.md` file you want
  205. to link to. The path to the file starts from the `content` directory.
  206. For example, linking to a file located at `content/pages/about.md` would be `[my link](./pages/about.md)`.
  207. ### Anchors
  208. Headers get an automatic id from their content in order to be able to add deep links.
  209. You can also choose, at the section level, whether to automatically insert an anchor link next to it. It is turned off by default
  210. but can be turned on by setting `insert_anchor = "left"` or `insert_anchor = "right"` in the `_index.md` file. `left` will insert
  211. the anchor link before the title text and right will insert it after.
  212. The default template is very basic and will need CSS tweaks in your project to look decent.
  213. It can easily be overwritten by creating a `anchor-link.html` file in the `templates` directory.
  214. ### Shortcodes
  215. Gutenberg uses markdown for content but sometimes you want to insert some HTML, for example for a YouTube video.
  216. Rather than copy/pasting the HTML around, Gutenberg supports shortcodes, allowing you to define templates using Tera and call those templates inside markdown.
  217. #### Using a shortcode
  218. There are 2 kinds of shortcodes: simple ones and those that take some content as body. All shortcodes need to be preceded by a blank line or they
  219. will be contained in a paragraph.
  220. Simple shortcodes are called the following way:
  221. ```markdown
  222. {{ youtube(id="my_youtube_id") }}
  223. ```
  224. Shortcodes with a body are called like so:
  225. ```markdown
  226. {% quote(author="Me", link="https://google.com") %}
  227. My quote
  228. {% end %}
  229. ```
  230. The shortcodes names are taken from the files they are defined in, for example a shortcode with the name youtube will try to render
  231. the template at `templates/shortcodes/youtube.html`.
  232. #### Built-in shortcodes
  233. Gutenberg comes with a few built-in shortcodes:
  234. - YouTube: embeds a YouTube player for the given YouTube `id`. Also takes an optional `autoplay` argument that can be set to `true`
  235. if wanted
  236. - Vimeo: embeds a Vimeo player for the given Vimeo `id`
  237. - Streamable: embeds a Streamable player for the given Streamable `id`
  238. - Gist: embeds a Github gist from the `url` given. Also takes an optional `file` argument if you only want to show one of the files
  239. #### Defining a shortcode
  240. All shortcodes need to be in the `templates/shortcodes` folder and their files to end with `.html`.
  241. Shortcodes templates are simple Tera templates, with all the args being directly accessible in the template.
  242. In case of shortcodes with a body, the body will be passed as the `body` variable.
  243. ## Example sites
  244. - [vincent.is](https://vincent.is): https://gitlab.com/Keats/vincent.is
  245. - [code<future](http://www.codelessfuture.com/)
  246. - http://t-rex.tileserver.ch (https://github.com/pka/t-rex-website/)
  247. - [adrien.is](https://adrien.is): https://github.com/Fandekasp/fandekasp.github.io
  248. - [Philipp Oppermann's blog](https://os.phil-opp.com/): https://github.com/phil-opp/blog_os/tree/master/blog
  249. - [seventeencups](https://www.seventeencups.net): https://github.com/17cupsofcoffee/seventeencups.net
  250. ## Adding syntax highlighting languages and themes
  251. ### Adding a syntax
  252. Syntax highlighting depends on submodules so ensure you load them first:
  253. ```bash
  254. $ git submodule update --init
  255. ```
  256. Gutenberg only works with syntaxes in the `.sublime-syntax` format. If your syntax
  257. is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on
  258. Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`.
  259. You can also add a submodule to the repository of the wanted syntax:
  260. ```bash
  261. $ cd sublime_syntaxes
  262. $ git submodule add https://github.com/elm-community/Elm.tmLanguage.git
  263. ```
  264. Note that you can also only copy manually the updated syntax definition file but this means
  265. Gutenberg won't be able to automatically update it.
  266. You can check for any updates to the current packages by running:
  267. ```bash
  268. $ git submodule update --remote --merge
  269. ```
  270. And finally from the root of the components/rendering crate run the following command:
  271. ```bash
  272. $ cargo run --example generate_sublime synpack ../../sublime_syntaxes ../../sublime_syntaxes/newlines.packdump ../../sublime_syntaxes/nonewlines.packdump
  273. ```
  274. ### Adding a theme
  275. A gallery containing lots of themes at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark.
  276. More themes can be easily added to gutenberg, just make a PR with the wanted theme added in the `sublime_themes` directory
  277. and run the following command from the root of the components/rendering:
  278. ```bash
  279. $ cargo run --example generate_sublime themepack ../../sublime_themes ../../sublime_themes/all.themedump
  280. ```
  281. You should see the list of themes being added.