Merge new-book into main

[TrialDragon]

Merges the new-book branch into main resolving conflicts along the way.

Closes #870
Closes #602

[BorisBoutillier]

I am kind of new to the website internals so bear with me for my missing knowledge.

1. A quick check that this didn't clobber anything it shouldn't.

I have gone through all the sections, on main and in this PR, and I have not found anything missing, but the quick-start replacing the book as expected.

2. Local validation using zola that the new book won't be visible to end users.

The new book, is hidden from links, and has the 'hidden' paragraph shown, but can still be accessed with the direct link URL/learn/book/, both when serving locally and when creating a build locally. I am not sure if the latter is intended, or if the final web-site is build differently than just zola build

3. Local validation using zola that contributors can show drafts and check their built pages.

I have been able to add a page and show my drafts, but I am not sure I did it the usual expected, I have yet to explicitly contribute pages to the site. a more seasoned contributor should double check this.

I did not use the formal 'review approved' as I feel my yet limited knowledge requires more seasoned/knowledgeable contributors to approve :)

[RomainMazB]

There are some tiny changes:

• a typo
• some link changes to avoid white blinking due to a redirection for the new quick start url
• codestyle

But my main concerns are about seo.
There is a redirection to handle the new url of the quick start, faq and migration guides but it sounds like Zola doesn't create redirection in children pages.

This mean that all the search engine referenced pages under /learn/book path, (excluding /learn/book/quick-start which is aliased by this PR) will now lead to a 404.

I am not sure Zola provides an easy way to handle this [Edit: I am now sure as this is a feature request]
To avoid this, we need create aliases for each page manually.

@TrialDragon to not do the job twice, I've submitted a PR in your branch, just merge it and all my review will be fixed.

[RomainMazB]

/learn/book/quick-start redirects to /learn/quick-start/introduction, we probably want to directly link this page instead to avoid white blinking redirection.

[RomainMazB]

Only one backtick is needed here on main.rs

[RomainMazB]

Missing [App] and [add_systems] link here to follow the page semantics.

Same on line 152, shouldn't we link Query struct?

[RomainMazB]

Typo: the function name is add_system**s**

[RomainMazB]

To reflect the previous typo fix, this line should be:

[`add_systems`]: https://docs.rs/bevy_app/latest/bevy_app/struct.App.html#method.add_systems`

[RomainMazB]

Codestyle, closing parenthesis and opening bracket should be on a new line, and should we expand the parameters on three lines to emphase them individually?

fn greet_people(
    time: Res<Time>,
    mut timer: ResMut<GreetTimer>,
    query: Query<&Name, With<Person>>
) {

[RomainMazB]

The quick start guide link should be on /learn/quick-start/introduction to avoid white page redirection blink as mentioned previously.

The problem is present in all the news, I won't mention all of them to not bloat this review.

[RomainMazB]

TL;DR;

I fixed the issue described here in the PR of the @TrialDragon branch

Description of the problem

@alice-i-cecile My review mostly concern only the first point you wanted to check,

1. A quick check that this didn't clobber anything it shouldn't.

For the second point,

2. Local validation using zola that the new book won't be visible to end users.

With the actual configuration, it's not totally the case, let me explain.

Even if there isn't direct internal link to the book, Zola will generate these pages and as confirmed by @BorisBoutillier, they will be accessible for the users who know the direct url.

This could be just ok, but our enemy are robots here.
Zola will still integrate these pages into the sitemap.xml file, meaning Google and other search engine will reference these pages and make them visible to the end user.

Plus, if we activate the internal Zola search bar, it will display those pages too.

Looking into the Zola documentation and with some local tests, we can fix this using this configuration in the configuration.toml file:

ignored_content = ['*/learn/book/**']

But!! Doing so, we break your third concern:

3. Local validation using zola that contributors can show drafts and check their built pages.

By adding this configuration, the pages are not generated and the contributors can't see their draft pages anymore.

Not sure how you would tackle this? We can add a notice into the website contributor guide to disable this option in local? Or maybe there is a way with environment variable to let it enable but activate the ignored_content only in the CI pipeline?

[EDIT]
Looking further, there is an open issue for this specific problem but it looks like it won't be fixed.
An alternative solution is mentioned in comment by Zola's maintainer which is to use the [extra] page configuration tag with a custom sitemap template to hide those pages.

A basic example:

+++
title = "Assets"
weight = 5
sort_by = "weight"
template = "docs-section.html"
page_template = "docs-section.html"
insert_anchor_links = "right"
[extra]
hidden = true
+++

With a sitemap template like this one (not tested):

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    {%- for sitemap_entry in entries %}
        {%- if !sitemap_entry.hidden %}
            <url>
                <loc>{{ sitemap_entry.permalink | escape_xml | safe }}</loc>
                {%- if sitemap_entry.updated %}
                <lastmod>{{ sitemap_entry.updated }}</lastmod>
                {%- endif %}
            </url>
        {%- endif %}
    {%- endfor %}
</urlset>

[TrialDragon]

Don't we already hide the public draft pages from the site map like this via robots.txt and disallowing all public draft pages?

Edit: Reading thru this again, apparently not. I wonder if it doesn't disallow children pages and sections of public draft sections meaning every single page and section has to be explicitly marked public draft... I'll look into this asap and see if that is avoidable in the macros for deciding which pages are disallowed.

[TrialDragon]

So, public draft does disallow children in robots.txt, but as Romain has shown stuff was still in sitemap, meaning disallowing isn't removing stuff from sitemap (maybe that isn't how it works to solve the issue? Not sure how that is supposed to work in zola), or public draft code for doing that is flawed. Either way I'm bringing in Romain's solution of marking everything hidden for now since it should work.

[alice-i-cecile]

1. A quick check that this didn't clobber anything it shouldn't.

Inspecting the diff, this looks good.

2. Local validation using zola that the new book won't be visible to end users.

No links are present, and I suspect this shouldn't get hidden.

3. Local validation using zola that contributors can show drafts and check their built pages.

This was easy to do by navigating to http://127.0.0.1:1111/learn/book after running zola serve.

[alice-i-cecile]

Reviewed and approved by @RomainMazB, as discussed on Discord.

I'm merging this now: follow-up work can be done in other PRs that are less terrible to review.