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 5.3KB

6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  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. A fast static site generator in a single binary with everything built-in.
  5. Documentation is available on [its site](https://www.getgutenberg.io/documentation/getting-started/installation/) or
  6. in the `docs/content` folder of the repository.
  7. ## Comparisons with other static site generators
  8. | | Gutenberg | Cobalt | Hugo | Pelican |
  9. |:-------------------------------:|:---------:|--------|------|---------|
  10. | Single binary | ✔ | ✔ | ✔ | ✕ |
  11. | Language | Rust | Rust | Go | Python |
  12. | Syntax highlighting | ✔ | ✔ | ✔ | ✔ |
  13. | Sass compilation | ✔ | ✔ | ✔ | ✔ |
  14. | Assets co-location | ✔ | ✔ | ✔ | ✔ |
  15. | i18n | ✕ | ✕ | ✔ | ✔ |
  16. | Image processing | ✔ | ✕ | ✔ | ✔ |
  17. | Sane & powerful template engine | ✔ | ~ | ~ | ✔ |
  18. | Themes | ✔ | ✕ | ✔ | ✔ |
  19. | Shortcodes | ✔ | ✕ | ✔ | ✔ |
  20. | Internal links | ✔ | ✕ | ✔ | ✔ |
  21. | Link checker | ✔ | ✕ | ✕ | ✔ |
  22. | Table of contents | ✔ | ✕ | ✔ | ✔ |
  23. | Automatic header anchors | ✔ | ✕ | ✔ | ✔ |
  24. | Aliases | ✔ | ✕ | ✔ | ✔ |
  25. | Pagination | ✔ | ✕ | ✔ | ✔ |
  26. | Custom taxonomies | ✔ | ✕ | ✔ | ✕ |
  27. | Search | ✔ | ✕ | ✕ | ✔ |
  28. | Data files | ✕ | ✔ | ✔ | ✕ |
  29. | LiveReload | ✔ | ✕ | ✔ | ✔ |
  30. | Netlify support | ✔ | ✕ | ✔ | ✕ |
  31. ### Supported content formats
  32. - Gutenberg: markdown
  33. - Cobalt: markdown
  34. - Hugo: markdown, asciidoc, org-mode
  35. - Pelican: reStructuredText, markdown, asciidoc, org-mode, whatever-you-want
  36. ### Template engine explanation
  37. Cobalt gets `~` as, while based on [Liquid](https://shopify.github.io/liquid/), the Rust library doesn't implement all its features but there is no documentation on what is and isn't implemented. The errors are also cryptic. Liquid itself is not powerful enough to do some of things you can do in Jinja2, Go templates or Tera.
  38. Hugo gets `~`. It is probably the most powerful template engine in the list after Jinja2 (hard to beat python code in templates) but personally drives me insane, to the point of writing my own template engine and static site generator. Yes, this is a bit biased.
  39. ### Pelican notes
  40. Many features of Pelican are coming from plugins, which might be tricky
  41. to use because of version mismatch or lacking documentation. Netlify supports Python
  42. and Pipenv but you still need to install your dependencies manually.
  43. ## Contributing
  44. As the documentation site is automatically built on commits to master, all development
  45. should happen on the `next` branch, unless it is fixing the current documentation.
  46. If you want a feature added or modified, please open an issue to discuss it before doing a PR.
  47. ### Adding syntax highlighting languages and themes
  48. #### Adding a syntax
  49. Syntax highlighting depends on submodules so ensure you load them first:
  50. ```bash
  51. $ git submodule update --init
  52. ```
  53. Gutenberg only works with syntaxes in the `.sublime-syntax` format. If your syntax
  54. is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on
  55. Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`.
  56. You can also add a submodule to the repository of the wanted syntax:
  57. ```bash
  58. $ cd sublime_syntaxes
  59. $ git submodule add https://github.com/elm-community/SublimeElmLanguageSupport
  60. ```
  61. Note that you can also only copy manually the updated syntax definition file but this means
  62. Gutenberg won't be able to automatically update it.
  63. You can check for any updates to the current packages by running:
  64. ```bash
  65. $ git submodule update --remote --merge
  66. ```
  67. And finally from the root of the components/highlighting crate run the following command:
  68. ```bash
  69. $ cargo run --example generate_sublime synpack ../../sublime_syntaxes ../../sublime_syntaxes/newlines.packdump
  70. ```
  71. #### Adding a theme
  72. A gallery containing lots of themes is located at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark.
  73. More themes can be easily added to gutenberg, just make a PR with the wanted theme added in the `sublime_themes` directory
  74. and run the following command from the root of the components/rendering:
  75. ```bash
  76. $ cargo run --example generate_sublime themepack ../../sublime_themes ../../sublime_themes/all.themedump
  77. ```
  78. You should see the list of themes being added.