Bevy: Switch to mdbook for documentation

[aevyrie]

Capturing a documentation discussion in Discord:

Would it make more sense to migrate the book to mdbook as the long term solution, instead of zola?

@cart responded:

cart Today at 2:51 PM
I've been playing around with that idea for awhile. It's clearly the more feature complete solution, but I don't want to lose the "integrated feel" of the current implementation. I also think using the same codebase for all website contributions keeps things nice and simple.
It's worth opening an issue to capture this

These are some of the pros/cons I value:

Pros:

• As the project grows, it may be desirable to split the documentation site from the promo site (the source, that is), and delegate this work to different owners.
• mdbook is already the defacto standard in the rust community, it will feel more familiar to users who are already in the rust ecosystem compared to a bespoke solution.
• zola is meant as a general purpose static site generator. mdbook is more feature complete for documentation and we gain any downstream documentation-related feature adds.
• Easy to build (only) the book locally for offline use.
• Built-in code playground.

Cons

• Less "integrated feel" compared to current implementation
• Added complexity of having separate documentation and website tooling/repos.

Edit: Changed the title to be a bit more descriptive.

[zicklag]

Just throwing my experience in here: I was pleasantly surprised to get the integrated feel of the documentation in the main site. It seemed very nice to me and when the site looked so nice it felt rather professional.

Not saying this should go one way or the other but that was my first impression of the current site.

[aevyrie]

I agree! For example, I think the Rocket documentation does this to great effect: https://rocket.rs/v0.4/guide/quickstart/

An alternative: the marketing "hook" showing bevy's ergonomics could be shown on the main site, like the overview page in rocket: https://rocket.rs/v0.4/overview/ to retain the integrated branding, and the extended learning documentation could be in mdbook to leverage its features.

I don't think there is a wrong answer here, it's a matter of balancing maintenance cost, branding, etc., and how cart currently values those things relative to each other.

[Keats]

Found this issue completely by chance while looking at Bevy.

Just a quick question as the creator of Zola, not trying to influence any decisions. Can you expand on

mdbook is more feature complete for documentation and we gain any downstream documentation-related feature adds

The only thing I'm aware of is running/testing Rust code in the book.

[aevyrie]

That's really the only software feature difference I'm aware of, yes. I'm sure you are much more familiar than I. 😄

To expand on my "feature complete" statement, what I should've said is that there are documentation specific anti-features in zola, such as the easy custom theming and customization - though I recognize this is subjective. I believe that having a consistent style and UX for documentation across the rust ecosystem is a really positive thing, especially for newer users (like me!). Any time I open "The Book" for a library, I know exactly what to expect in terms of tone, style, and navigation. That's not to say you can't customize mdbook, or that zola prevents you from producing a similar tone/style/nav. However, if every rust library had their own custom, slightly different docs, it would make for a disjointed documentation ecosystem. As someone who's relied on countless "_The xyz Book_"s, the consistency is something I've really grown to appreciate. In the same way that rust API docs are consistent across all libraries, for people like me that need more hand holding and default to a project's _Book_ when starting, having these be equally as consistent as the API docs is really helpful.

That said, I hope it's clear I'm not lamenting the lack of any specific feature in zola, it's more to do with the goals of each project. Zola is a fast, easy to use, static site generator, with the (presumed) goal of making any static site you can think of. Mdbook, on the other hand, targets the creation of rust library documentation, and has apparently become the defacto standard for serving that purpose. As mdbook continues on its path as a project, I can be confident that any features it adds will align with the goals of this task, which is to create yet another _The Book_.

Finally, I'd be remiss if I didn't thank you for your work on zola, I do really like using it, and I agree that it's a great fit for making the Bevy website 😃. Thanks!

[Keats]

there are documentation specific anti-features in zola, such as the easy custom theming and customization - though I recognize this is subjective. I believe that having a consistent style and UX for documentation across the rust ecosystem is a really positive thing, especially for newer users (like me!).

That's interesting, I didn't think about it that way and I have the exact opposite viewpoint. I'm a bit annoyed when all I get for documentation is a mdbook instead of something like https://rocket.rs/v0.4/guide/ or https://docs.djangoproject.com/en/3.1/ as it's very basic/bland/disconnected. If the book is the only documentation (eg https://pyo3.rs/v0.11.1/) it's completely fine but if you have a project with a brand, it's a shame imo to remove it for the documentation

Anyway it's up to the creator and the contributors to pick whatever they prefer! Thanks for the kind words @aevyrie .

[cart]

My personal (and only) "big" reason to switch to mdbook is that right now the bevy "nested subsection" templates/macros in bevy's zola site are _truly unmaintainable_. They might look relatively ok at first glance, but once you start considering control flow and "state" you will realize that they are a crime against humanity. As far as I'm concerned, the "hygiene" restrictions in the Tera template system forced my hand / I couldn't find a better way to do this. I was hoping I could just write them once and leave them as-is, but it looks like a recent zola update broke them. So now I'm confronted with the decision to fix a bug in these _absolute monstrosities_ or move to something like mdbook that protects me from this evil. If someone has a better zola/tera solution to the problem (that doesn't involve javascript) that would make me very happy. Otherwise I will likely start investigating using a themed version of mdbook

Note that this is not a critique of Zola or Tera. I think they are both fantastic, featureful, easy to use projects. This just felt a bit like a "square peg round hole" situation.

[CleanCut]

😱 Sounds like mdbook is the sane path to me.

[aevyrie]

My personal (and only) "big" reason to switch to mdbook is that right now the bevy "nested subsection" templates/macros in bevy's zola site are _truly unmaintainable_. They might look relatively ok at first glance, but once you start considering control flow and "state" you will realize that they are a crime against humanity.

I understand that branding is an important consideration in using zola for this purpose. What if the website, instead of being a comprehensive guide, was just a high-level overview to get a taste of Bevy? (i.e. the "hook") This could be a static page without heirarchy or navigation; a simple step by step like a shorter version of the bevy introduction which I absolutely loved.

[Keats]

Any reasons the pages are actually sections? It's easier if they are not, you can just copy the templates from https://github.com/getzola/book
Otherwise I made a PR to make it simpler: https://github.com/bevyengine/bevy-website/pull/58 but I only spent a few minutes on it so I might have missed something.

[cart]

IIRC I didn't use the getzola/book templates because they didn't appear to support nesting more than one level deep. The current bevy book content doesn't need that, but i expect us to eventually want it.

[Keats]

Yep it doesn't right now. The PR doesn't either, but its just a matter of adding a nested loop when building the list of paths. I could add it to the PR so it's supported out of the box when needed.

[cart]

That would be much appreciated and would make me very inclined to stick with zola :smile:

Thanks!

[Keats]

Done. If you have annoying issues like that or improvements you would like to see, please open issues on Tera/Zola! Always good to have more feedback.