-
Notifications
You must be signed in to change notification settings - Fork 908
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Significantly improve the README #1373
Changes from all commits
a7c3c71
36e4d9d
b69afd8
8c385f9
7379cba
e8d51ed
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,58 +1,172 @@ | ||||||
# zola (né Gutenberg) | ||||||
|
||||||
[![Build Status](https://dev.azure.com/getzola/zola/_apis/build/status/getzola.zola?branchName=master)](https://dev.azure.com/getzola/zola/_build/latest?definitionId=1&branchName=master) | ||||||
|
||||||
A fast static site generator in a single binary with everything built-in. | ||||||
|
||||||
Documentation is available on [its site](https://www.getzola.org/documentation/getting-started/installation/) or | ||||||
in the `docs/content` folder of the repository and the community can use [its forum](https://zola.discourse.group). | ||||||
**zola version:** 0.13.0 ([CHANGELOG](CHANGELOG.md)) | ||||||
|
||||||
**Test results:** [![Build Status](https://dev.azure.com/getzola/zola/_apis/build/status/getzola.zola?branchName=master)](https://dev.azure.com/getzola/zola/_build/latest?definitionId=1&branchName=master) | ||||||
|
||||||
[**Minimum Supported Rust Version**](azure-pipelines.yml#L24) | ||||||
|
||||||
## Intro | ||||||
|
||||||
zola, previously known as gutenberg, is a simple and fast static site generator written in Rust. It aims to do one thing and do it well, with everything you need built-in. Documentation is available on [getzola.org](https://www.getzola.org/documentation/getting-started/installation/) or in the `docs/content` folder. A community forum for support, ideas and feedback is available at [zola.discourse.group](https://zola.discourse.group). | ||||||
|
||||||
Zola provides services to many people already (see [EXAMPLES.md](EXAMPLES.md)), but has not been stabilized yet. This doesn't mean that zola itself is unstable and will crash randomly, but rather than configuration and usage patterns will continue to change for the foreseeable future in order to make zola more useful and more robust. | ||||||
|
||||||
Feature requests are always welcome, although we carefully consider each new feature for its perceived usefulness, relative to the complexity for implementation/maintaining. Pull requests for new features (patches) are also welcome, but we encourage contributors to first start discussions on [the forums](https://zola.discourse.group/) to collect user feedback on their ideas. | ||||||
|
||||||
Bug reports and patches for those are welcome at any time on our repository. If something is getting in your way or otherwise painful to use, it's probably a bug for other people as well, so do not hesitate to report it, so it can be fixed for everyone once and for all. | ||||||
|
||||||
## Demo | ||||||
|
||||||
[getzola.org](https://www.getzola.org/) is entirely produced with zola. Please head over to [EXAMPLES.md](EXAMPLES.md) for more example sites produced with zola. | ||||||
|
||||||
## Comparisons with other static site generators | ||||||
|
||||||
| | Zola | Cobalt | Hugo | Pelican | | ||||||
zola may or may not be the right tool for you. If you would like to see at a glance the pro's and con's of using Zola, here you will find some tables comparing it with [Cobalt](https://cobalt-org.github.io/), [Hugo](https://gohugo.io/) and [Pelican](https://blog.getpelican.com/). This comparison tries to be unbiased (factual), however some information is missing, and we are of course more familiar with the support of certain features in Zola (compared to other tools), so feedback and patches are welcome to improve it. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
**Note:** Many features of Pelican come from plugins, which might be tricky to use because of a version mismatch or inadequate documentation. Netlify supports Python and Pipenv but you still need to install your dependencies manually. | ||||||
|
||||||
### High-level overview | ||||||
|
||||||
| | [Zola](https://getzola.org/) | [Cobalt](https://cobalt-org.github.io/) | [Hugo](https://gohugo.io/) | [Pelican](https://blog.getpelican.com/) | | ||||||
|:--------------------------------|:------:|:------:|:------:|:-------:| | ||||||
| Single binary | ![yes] | ![yes] | ![yes] | ![no] | | ||||||
| Language | Rust | Rust | Go | Python | | ||||||
| Syntax highlighting | ![yes] | ![yes] | ![yes] | ![yes] | | ||||||
| Sass compilation | ![yes] | ![yes] | ![yes] | ![yes] | | ||||||
| Assets co-location | ![yes] | ![yes] | ![yes] | ![yes] | | ||||||
| Multilingual site | ![ehh] | ![no] | ![yes] | ![yes] | | ||||||
| Image processing | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Sane & powerful template engine | ![yes] | ![yes] | ![ehh] | ![yes] | | ||||||
| Themes | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Shortcodes | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Internal links | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Link checker | ![yes] | ![no] | ![no] | ![yes] | | ||||||
| Table of contents | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Automatic header anchors | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Syntax highlighting | [![yes]](https://www.getzola.org/documentation/content/syntax-highlighting/) | ![yes] | ![yes] | ![yes] | | ||||||
| Sass compilation | [![yes]](https://www.getzola.org/documentation/content/sass/) | ![yes] | ![yes] | ![yes] | | ||||||
| Multilingual site | [![ehh]](https://www.getzola.org/documentation/content/multilingual/) | ![no] | ![yes] | ![yes] | | ||||||
| Image processing | [![yes]](https://www.getzola.org/documentation/content/image-processing/) | ![no] | ![yes] | ![yes] | | ||||||
| Link checker | [![yes]](https://www.getzola.org/documentation/getting-started/cli-usage/#check) | ![no] | ![no] | ![yes] | | ||||||
| Search | [![ehh]](https://www.getzola.org/documentation/content/search/) | ![no] | ![no] | ![yes] | | ||||||
| Data files | [![yes]](https://www.getzola.org/documentation/templates/overview/#load-data) | ![yes] | ![yes] | ![no] | | ||||||
| LiveReload | [![yes]](https://www.getzola.org/documentation/getting-started/cli-usage/#serve) | ![no] | ![yes] | ![yes] | | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not a bit fan of splitting the tables. I've heard a few people liking having all the "features" listed in one list so they scan for what they need/use to see which tools is the best for them. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I agree a single-page comparison is really useful. But personally i found one huge disorganized table was really confusing when looking for a specific feature. Don't you think it's a lot more clear when the features support table is split like this while still residing on the same page? I started a topic on the forums about it to collect more feedback. |
||||||
| Configurable error/warn levels | ![no] | ![no] | ![yes] | ? | | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I moved the "warn/error on broken links" here in the high-level overview and made more clear it's about error/warning management not about links. Is it better? |
||||||
|
||||||
**Notes:** | ||||||
|
||||||
- *Multilingual site* | ||||||
- zola gets ![ehh] because despite having a basic translations system, it is being redesigned to evade its current limitations (see [discussion on the forum](https://zola.discourse.group/t/rfc-internationalization-system-rework/546)) ; also, custom `base_url` settings per language is currently not supported | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I just changed this. Is it clear like this? |
||||||
- *Search* | ||||||
- zola gets ![ehh] because search engine is disabled by default in some languages, as explained [in the docs](https://www.getzola.org/documentation/content/multilingual/#configuration) | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not sure about that being a There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I agree the tradeoff is good, but don't you think this limitation should be advertised in the comparison table? |
||||||
|
||||||
### Content library | ||||||
|
||||||
| | [Zola](https://getzola.org/) | [Cobalt](https://cobalt-org.github.io/) | [Hugo](https://gohugo.io/) | [Pelican](https://blog.getpelican.com/) | | ||||||
|:--------------------------------|:------:|:------:|:------:|:-------:| | ||||||
| Aliases | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Pagination | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Custom taxonomies | ![yes] | ![no] | ![yes] | ![no] | | ||||||
| Search | ![yes] | ![no] | ![no] | ![yes] | | ||||||
| Data files | ![yes] | ![yes] | ![yes] | ![no] | | ||||||
| LiveReload | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Netlify support | ![yes] | ![no] | ![yes] | ![no] | | ||||||
| Vercel support | ![yes] | ![no] | ![yes] | ![yes] | | ||||||
| Assets co-location | [![ehh]](https://www.getzola.org/documentation/content/overview/#asset-colocation) | ![yes] | ![yes] | ![yes] | | ||||||
| HTML shortcodes | [![yes]](https://www.getzola.org/documentation/content/shortcodes/) | ![no] | ![yes] | ![yes] | | ||||||
| Format-specific shortcodes | [![yes]](https://www.getzola.org/documentation/content/shortcodes/) | ? | ? | ? | | ||||||
| Internal links | [![ehh]](https://www.getzola.org/documentation/content/linking/) | ![no] | ![yes] | ![yes] | | ||||||
| Custom taxonomies | [![yes]](https://www.getzola.org/documentation/content/taxonomies/) | ![no] | ![yes] | ![no] | | ||||||
| Multiple static mounts | [![no]](https://github.com/getzola/zola/issues/499) | ![no] | [![yes]](https://gohugo.io/hugo-modules/configuration/#module-config-mounts) | ? | | ||||||
|
||||||
**Notes:** | ||||||
|
||||||
- *Assets co-location* | ||||||
- zola receives ![ehh] because assets cannot be shared across pages/sections, despite living in the same folder ([discussion on the forum](https://zola.discourse.group/t/reusing-markdown-docs-from-github-repo-in-zola-site/776)) | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. how does cobalt/hugo solve that to get a There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure. That was simply copied over from the current README. |
||||||
- *Internal links* | ||||||
- zola receives ![ehh] because in case you are building your website for a subfolder of the webroot (for example `https://myserver.example/mysite`), linking to static assets (or another page's colocated assets) requires using a dedicated shortcode (see discussion about [path unification](https://github.com/getzola/zola/issues/977) for how to improve that) ; sites built for the webroot of a domain are unaffected by this limitation | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it more clear like this? |
||||||
|
||||||
The following input formats are supported: | ||||||
|
||||||
| | [Zola](https://getzola.org/) | [Cobalt](https://cobalt-org.github.io/) | [Hugo](https://gohugo.io/) | [Pelican](https://blog.getpelican.com/) | | ||||||
|:--------------------------------|:------:|:------:|:------:|:-------:| | ||||||
| Markdown | ![yes] | ![yes] | ![yes] | ![yes] | | ||||||
| AsciiDoc | [![no]](https://github.com/getzola/zola/issues/1160) | ![no] | ![yes] | ![yes] | | ||||||
| org-mode | [![no]](https://zola.discourse.group/t/support-for-org-mode/789) | ![no] | ![yes] | ![yes] | | ||||||
| reStructuredText | [![no]](https://zola.discourse.group/t/alternative-input-formats/76) | ![no] | ![no] | ![yes] | | ||||||
| extensible (plugins) | ![no] | ![no] | ![no] | ![yes] | | ||||||
southerntofu marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
### Output rendering | ||||||
|
||||||
| | [Zola](https://getzola.org/) | [Cobalt](https://cobalt-org.github.io/) | [Hugo](https://gohugo.io/) | [Pelican](https://blog.getpelican.com/) | | ||||||
|:--------------------------------|:------:|:------:|:------:|:-------:| | ||||||
| Breadcrumbs | ![yes] | ![no] | ![no] | ![yes] | | ||||||
| Custom output formats | ![no] | ![no] | ![yes] | ![no] | | ||||||
| Automatic header anchors | [![yes]](https://www.getzola.org/documentation/content/linking/#anchor-insertion) | ![no] | ![yes] | ![yes] | | ||||||
| Pagination | [![yes]](https://www.getzola.org/documentation/templates/pagination/) | ![no] | ![yes] | ![yes] | | ||||||
| Table of contents | [![yes]](https://www.getzola.org/documentation/templates/pages-sections/#table-of-contents) | ![no] | ![yes] | ![yes] | | ||||||
| Themes | [![yes]](https://www.getzola.org/documentation/themes/creating-a-theme/) | ![no] | ![yes] | ![yes] | | ||||||
| Extensible themes | [![yes]](https://www.getzola.org/documentation/themes/extending-a-theme) | ? | [![yes]](https://gohugo.io/templates/base/) | [![yes]](https://docs.getpelican.com/en/latest/themes.html#inheritance) | | ||||||
| Sane & powerful template engine | [![yes]](https://www.getzola.org/documentation/templates/overview/) | ![yes] | ![ehh] | ![yes] | | ||||||
| Custom output formats | [![no]](https://zola.discourse.group/t/proposal-custom-output-formats/68/4) | ![no] | ![yes] | ![no] | | ||||||
| URL templates | [![no]](https://github.com/getzola/zola/issues/635) | ![no] | [![yes]](https://gohugo.io/content-management/urls/#permalinks-configuration-example) | ? | | ||||||
| UglyURLs | [![no]](https://github.com/getzola/zola/issues/840) | ![no] | [![yes]](https://gohugo.io/content-management/urls/#ugly-urls) | ? | | ||||||
| Relative URLs | [![ehh]](https://github.com/getzola/zola/issues/711) | ![no] | [![yes]](https://gohugo.io/content-management/urls/#relative-urls) | ? | | ||||||
| [Backlinks](https://en.wikipedia.org/wiki/Backlink) | ![no] | ![no] | [![no]](https://github.com/gohugoio/hugo/issues/8077) | ? | | ||||||
| Diagrams | [![no]](https://zola.discourse.group/t/diagramming-tool-integrations-plantuml-svgbob-graphviz-etc/269) | ![no] | [![no]](https://github.com/gohugoio/hugo/issues/7765) | [![yes]](https://github.com/getpelican/pelican-plugins/tree/master/plantuml) | | ||||||
|
||||||
**Notes:** | ||||||
|
||||||
- *Sane & powerful template engine* | ||||||
- hugo gets ![ehh] because golang templates are simply not meant for webdesign (despite being very powerful), to the point of driving @Keats insane to create his own template engine ([tera](https://github.com/keats/tera)) and static-site generator (zola) ; yes this is a little biased | ||||||
- *Relative URLs* | ||||||
- zola gets ![ehh] because it can only produce relative URLs for the webroot, not a subfolder (see discussion about [path unification](https://github.com/getzola/zola/issues/711)) | ||||||
|
||||||
### Deployment integrations | ||||||
|
||||||
While it's usually possible to use any kind of static site generator to deploy to a website, some platforms have restrictions and specific tooling to publish content. Here's some example documentation for deploying on specific platforms: | ||||||
|
||||||
| | [Zola](https://getzola.org/) | [Cobalt](https://cobalt-org.github.io/) | [Hugo](https://gohugo.io/) | [Pelican](https://blog.getpelican.com/) | | ||||||
|:------------------------------------|:------:|:------:|:------:|:-------:| | ||||||
| [Netlify](https://www.netlify.com/) | [![yes]](https://www.getzola.org/documentation/deployment/netlify/) | ![no] | ![yes] | ![no] | | ||||||
| [Vercel](https://vercel.com/) | [![yes]](https://www.getzola.org/documentation/deployment/vercel/) | ![no] | ![yes] | ![yes] | | ||||||
| [SourceHut](https://srht.site/) | [![yes]](https://www.getzola.org/documentation/deployment/sourcehut/) | ? | ? | ? | | ||||||
| [Github](https://pages.github.com/) | [![yes]](https://www.getzola.org/documentation/deployment/github-pages/) | ? | ![yes] | ![yes] | | ||||||
| [Gitlab](https://docs.gitlab.com/ee/user/project/pages/) | [![yes]](https://www.getzola.org/documentation/deployment/gitlab-pages/) | ? | ![yes] | ![yes] | | ||||||
|
||||||
## Contributing | ||||||
|
||||||
If you would like to contribute to improve zola together as a community, there are many ways to do so. In this section, we outline a few ways you could help the zola project. If you're looking to make a contribution now, please read [CONTRIBUTING.md](CONTRIBUTING.md). | ||||||
|
||||||
### Documentation and pro tips | ||||||
|
||||||
When you notice something isn't clear in the documentation, you may submit a patch to improve it for every one else. If you're doing something which you think could be of interest to other folks, please write about it [on the forums](https://zola.discourse.group/). If you notice some usage patterns emerging on the forums, feel free to turn that into a documentation page to help other people achieve the same goals. | ||||||
|
||||||
### Areas to improve | ||||||
|
||||||
### Supported content formats | ||||||
Despite being three decades old, the world wide web isn't always the most convenient platform to use. zola tries to make your life better, but if you're experiencing difficulties with it, don't hesitate to report those. Please be clear about what was confusing or unexpected regarding what you tried to achieve. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this is kind of a duplicate of a paragraph above. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't think so? Documentation said about interesting hacks. This "Areas to improve" paragraph is about what is unexpected/inconsistent. But i can remove the paragraph if you don't like it. |
||||||
|
||||||
- Zola: markdown | ||||||
- Cobalt: markdown | ||||||
- Hugo: markdown, asciidoc, org-mode | ||||||
- Pelican: reStructuredText, markdown, asciidoc, org-mode, whatever-you-want | ||||||
zola doesn't shine for all use cases we can think of. We want to improve certain things in the next release, and could use feedback in particular for: | ||||||
|
||||||
### ![ehh] explanations | ||||||
- a better [translations system](https://zola.discourse.group/t/rfc-internationalization-system-rework/546) | ||||||
- a [unified path](https://github.com/getzola/zola/issues/977) representation | ||||||
|
||||||
Hugo gets ![ehh] for the template engine because while it is probably the most powerful template engine in the list (after Jinja2) it personally drives me insane, to the point of writing my own template engine and static site generator. Yes, this is a bit biased. | ||||||
Additionally, we currently only support Markdown input and HTML/Atom output. Following some feature requests, we are considering to add support for more formats as a long-term goal (other priorities apply for the next releases). However, we do not want to create more problems down the road (inconsistencies and maintenance burden), and so we would appreciate feedback on how to implement: | ||||||
|
||||||
Zola gets ![ehh] for multi-language support as it only has a basic support and does not (yet) offer things like i18n in templates. | ||||||
- support for [non-Markdown input formats](https://zola.discourse.group/t/alternative-input-formats/76) | ||||||
- support for [non-HTML output formats](https://zola.discourse.group/t/proposal-custom-output-formats/68/4) | ||||||
southerntofu marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
### Pelican notes | ||||||
### Translations | ||||||
|
||||||
The documentation is currently only available in English, which is a shame because most of the world does not speak english. If you would like to help making zola available to more people, feel free to translate documentation in your language. | ||||||
|
||||||
### Programming | ||||||
|
||||||
Some areas of zola could be improved. If you're just getting started, we maintain a list of [good first issues](https://github.com/getzola/zola/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) to get you started hacking on the codebase. If you'd like to tackle some harder problems, you can take a look at the ![ehh] and ![no] features from the comparison table. Additionally, we also have a list of [issues we'd like help on](https://github.com/getzola/zola/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). | ||||||
|
||||||
Some (upstream) projects we rely on to build zola could use some help: | ||||||
|
||||||
- [tera](https://github.com/keats/tera/) rendering engine has some issues marked [`good first issue`](https://github.com/Keats/tera/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) as well as some [`help wanted`](https://github.com/Keats/tera/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) | ||||||
- [pest](https://github.com/pest-parser/pest/issues/489#issuecomment-775114684) parser is [looking for new contributors](https://github.com/pest-parser/pest/issues/489#issuecomment-775114684) | ||||||
|
||||||
### Packaging | ||||||
|
||||||
zola is not yet packaged for all systems. An updated list of zola packages can be found [in the documentation](https://www.getzola.org/documentation/getting-started/installation/). Some platforms we would like to have packages for include: | ||||||
|
||||||
- [Debian](https://debian.org/): zola is currently unavailable, even on `experimental` ; ideally, we would like to support [backports](https://backports.debian.org/) on `stable` as well, because zola is evolving fast | ||||||
- [nix](https://nixos.org/): zola on nix is outdated (v0.12.0 as of writing this) | ||||||
- [GNU guix](https://guix.gnu.org/): zola is currently unavailable in GNU guix | ||||||
|
||||||
## License | ||||||
|
||||||
[MIT license](LICENSE) | ||||||
|
||||||
Many features of Pelican come from plugins, which might be tricky to use because of a version mismatch or inadequate documentation. Netlify supports Python and Pipenv but you still need to install your dependencies manually. | ||||||
|
||||||
[yes]: ./is-yes.svg | ||||||
[ehh]: ./is-ehh.svg | ||||||
[no]: ./is-no.svg | ||||||
|
||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.