Significantly improve the README #1373

southerntofu · 2021-02-21T17:33:59Z

I spent some time to try and improve the README file. What do you think?

You can preview it here

southerntofu · 2021-02-21T18:01:14Z

Besides the obvious text additions, i added quite some stuff in the comparison table. I tried to make sure every feature that says is supported has a corresponding link to the docs (only for breadcrumbs i could not find) and tried to link to issues/forums where a feature was "no" or "ehh".

Keats

I like most of the changes!
I left some comments on the bits that need to be changed imo but that's better.

README.md

Keats · 2021-02-22T08:18:25Z

README.md

+| 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] |


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.

people liking having all the "features" listed in one list

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.

Keats · 2021-02-22T08:20:29Z

README.md

+- *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))
+- *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)


I'm not sure about that being a ehh. There is a flag built-in if you need to enable it for Chinese/Japanese but to get a yes we would need to give everyone a 90MB binary where 80% is something a good chunk of users are not going to use? It doesn't sound like an improvement to me.

I agree the tradeoff is good, but don't you think this limitation should be advertised in the comparison table?

README.md

Keats · 2021-02-22T08:37:05Z

README.md


-### 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.


I think this is kind of a duplicate of a paragraph above.

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.

README.md

southerntofu · 2021-02-22T13:18:07Z

README.md

+- *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))
+- *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


Is it more clear like this?

southerntofu · 2021-02-22T13:20:25Z

README.md

+**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


I just changed this. Is it clear like this?

southerntofu · 2021-02-22T13:21:09Z

README.md

+| 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] |
+| Configurable error/warn levels | ![no] | ![no] | ![yes] | ? |


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?

southerntofu · 2021-02-22T13:31:35Z

Ready for new review. I made sure to leave review notes of mine where i introduced changes since your review. So normally you only have to check out the open conversations.

CGMossa · 2023-05-14T15:18:48Z

README.md

+
+## 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).


Suggested change

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, 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).

CGMossa · 2023-05-14T15:19:54Z

README.md


 ## 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.


Suggested change

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.

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.

Significantly improve the README

a7c3c71

Keats requested changes Feb 22, 2021

View reviewed changes

southerntofu added 4 commits February 22, 2021 13:50

Link to MSRV + getzola.org example + more docs links

36e4d9d

Areas to improve

b69afd8

Configurable error/warn levels

8c385f9

Internal links clarification

7379cba

southerntofu commented Feb 22, 2021

View reviewed changes

Multilingual clarification

e8d51ed

southerntofu commented Feb 22, 2021

View reviewed changes

Keats mentioned this pull request Mar 7, 2021

Compare with Jekyll #1393

Closed

Keats force-pushed the next branch from 62981a3 to 4aa38e9 Compare August 2, 2021 11:43

Keats force-pushed the next branch from 040b0de to 88e5c6e Compare August 12, 2021 06:55

Keats force-pushed the next branch 2 times, most recently from 1e55db1 to 3155662 Compare December 9, 2021 21:11

Keats force-pushed the next branch from 189c37d to 6238b36 Compare January 23, 2022 13:38

Keats force-pushed the next branch from 36726be to fd05225 Compare February 14, 2022 10:08

Keats force-pushed the next branch from 52a950c to bf7dbfe Compare July 10, 2022 14:54

Keats force-pushed the next branch from 67d0287 to 4a40ac0 Compare August 14, 2022 14:10

Keats force-pushed the next branch from 2f017fb to 991d7b0 Compare August 22, 2022 20:34

Keats force-pushed the next branch from acfb50c to a4c3ce7 Compare February 16, 2023 21:41

Keats force-pushed the next branch from a4142dd to 99c2bfa Compare February 24, 2023 21:21

Keats force-pushed the next branch from 9744b18 to 8d16d17 Compare March 19, 2023 19:37

CGMossa reviewed May 14, 2023

View reviewed changes

Keats force-pushed the next branch from 7f5d1a6 to e5f3026 Compare December 19, 2023 12:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Significantly improve the README #1373

Significantly improve the README #1373

southerntofu commented Feb 21, 2021 •

edited

southerntofu commented Feb 21, 2021

Keats left a comment

Keats Feb 22, 2021

southerntofu Feb 22, 2021 •

edited

Keats Feb 22, 2021

southerntofu Feb 22, 2021

Keats Feb 22, 2021

southerntofu Feb 22, 2021

southerntofu Feb 22, 2021

southerntofu Feb 22, 2021

southerntofu Feb 22, 2021

southerntofu commented Feb 22, 2021

CGMossa May 14, 2023

CGMossa May 14, 2023


		### 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.


		## 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).

Significantly improve the README #1373

Are you sure you want to change the base?

Significantly improve the README #1373

Conversation

southerntofu commented Feb 21, 2021 • edited

southerntofu commented Feb 21, 2021

Keats left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

southerntofu Feb 22, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

southerntofu commented Feb 22, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

southerntofu commented Feb 21, 2021 •

edited

southerntofu Feb 22, 2021 •

edited