Add support for nested documentation sections (like Guides)

[lmammino]

This PR adds support for nested documentation sections like what is currently being proposed with "Guides" in fastify/fastify#2610.

Current status

Status: DRAFT

There are still some major issues with the current implementation and some more work to do.

See the following 2 pictures:

Nested documentation section index (PIC1)

Nested documentation page (PIC2)

TODO list

• Fix broken links in nested documentation section index pages (PIC 1 issue 1)
• Remove nested doc pages from top-level Table of Contents (PIC 1 issue 2)
• In nested documentation pages update breadcrumb menu as necessary (PIC 2 issue 1)
• Add special link remapping rule for CONTRIBUTING.md (PIC 2 issue 2)
• In nested documentation pages show in the menu with the ToC only pages for the current section (PIC 2 issue 4)
• Suggest necessary changes in Add contributing guide fastify#2610 to comply with what expected in this implementation (e.g. how to define links in the index pages and markdown formatting issues as in PIC2 issue 3)
• Try to move all the pages that belong to the API section to an API subfolder
• Publish a draft release of the new docs with all the changes above and get help on testing

[jsumners]

Broken TOC is my fault. I fixed it in the original PR.

What is wrong with the contributing link? It references the root of the site tree.

Let's shoot for the minimum of what works. Don't worry about trying to expose a document's embedded TOC in the sidebar menu.

[lmammino]

Broken TOC is my fault. I fixed it in the original PR.

Thanks

What is wrong with the contributing link? It references the root of the site tree.

We simply don't process CONTRIBUTING.md on the website. We should just make sure the link goes to the repository for that file. In that sense, we need to revisit the link-remapping rules and make sure that this one gets processed correctly

Let's shoot for the minimum of what works. Don't worry about trying to expose a document's embedded TOC in the sidebar menu.

Fair point, we can leave that one for last and maybe add it in a separate PR

[jsumners]

@lmammino I have another guide I'd like to write. How can I help move this along?

[lmammino]

Hey @jsumners, sorry again for the delay on this. I should be able to restart the work on this next week. Hopefully, i can find enough time to be able to ship a first PR .

[jsumners]

I decided to add my new doc as a reference doc. It made more sense to do so anyway.

[luisorbaiceta]

Is this still a thing? I can work on it and take it from here!

[lmammino]

hey @luisorbaiceta, we would still love to get this done and I'd be more than happy to hand over the work. Let me know if the current status makes sense to you. I am happy to discuss the current approach but I am not prescriptive. If you realize the are other valid approaches let's explore them as well!

[luisorbaiceta]

Let me know if the current status makes sense to you.

I'm taking a look at it right now. Will let you know if any doubt comes up! 👌

[luisorbaiceta]

I'm having some trouble during the build proccess. I have done as suggested in #241 by removing the content hash plugin (It´s the only way to get it working on Windows) and added the fix. Now files are being served (except for the bg-pattern-dark.png , that gets rendered like this /images\bg-pattern-dark.png).

The thing is that I expect the local instance of the website to look like the current fastify one, but It differs here:

Am I missing something? Is this a Windows thing?

[jsumners]

It might be easier to re-create this PR from scratch.

[luisorbaiceta]

The problem is that even if I build it from the master branch I still have the problem shown in the images above

[jsumners]

Please describe what problem I am supposed to be seeing in the screenshot. Or add some arrows to it pointing out the differences.

[luisorbaiceta]

Please describe what problem I am supposed to be seeing in the screenshot. Or add some arrows to it pointing out the differences.

I've updated the comment above

[jsumners]

🤷‍♂️

We will need to wait for the expert advice of @lmammino.

[lmammino]

Hey sorry for the delay, @luisorbaiceta.

Regarding the graphic discrepancies, I think it's because the master branch is a bit ahead of this branch, so you might need to pull the changes or rebase.

Regarding the background image, I am not currently sure why that's happening but I don't expect anything major. I think we can consider this a minor concern and not a blocker for now.

Finally, regarding the hashes, that's something we'll need to address because we will need hashes in the final production build (otherwise new changes will not show up live since the CDN does not invalidate the cache on deployments — except for HTML files — but instead it relies on assets having different URLs).

On this last point, I would say don't worry too much for now, meaning don't take this as a blocker. We can either figure out how to replace that content-hash plugin or I can do the last finishing touches and the final release once everything else is done.

Apologies if this is in a bit of a messy state right now.

By the way, what @jsumners suggested:

It might be easier to re-create this PR from scratch.

It's a totally valid approach if you feel it will allow you to do progress faster! So don't feel constrained by what's currently here!

[luisorbaiceta]

Regarding the graphic discrepancies, I think it's because the master branch is a bit ahead of this branch, so you might need to pull the changes or rebase.

The thing is I have also tried building from the master branch and I still get the same discrepancies...

Finally, regarding the hashes, that's something we'll need to address because we will need hashes in the final production build (otherwise new changes will not show up live since the CDN does not invalidate the cache on deployments — except for HTML files — but instead it relies on assets having different URLs).

I will adopt the fix mentioned in #241 but won't commit It to the PR so we can address this issue in another moment

Edit:

After having tried with a Macbook I can now confirm that is a Windows issue @lmammino

[jsumners]

@luisorbaiceta now that the Windows issue is resolved, do you plan to come back to this?

[luisorbaiceta]

Yes! @jsumners, I hope to have this done by next week

Update:

I haven't had the chance to take over this yet, hopefully I will find a gap next week 😬

[jsumners]

Yes! @jsumners, I hope to have this done by next week

🎉

[jsumners]

Just checking back in to see if this is still something you want/plan to work on @luisorbaiceta.

[luisorbaiceta]

Hi everyone! I'm back from vacation and working on this.

It will really save me a lot of time to understand what are we exactly trying to achieve (maybe some reference to a similar website with TOC), and to update the checklist with the current status. I have merged with the latest updates from master and there are some doubts that are coming up.

I have enumerated three features in the image above.

If I am correct, number 2 is what we are trying to achieve. Right now there are some sections that are showing a table of contents but without a proper title.

I think that if we are going to implement this feature it will also be a good think to add number 1 and remove number 3 as It will become redundant from the user experience point of view. What do you think?

[jsumners]

Right now the site only generates pages for files in docs/. If docs/guides/foo.md exists, it will not get a menu entry.

[luisorbaiceta]

Right now the site only generates pages for files in docs/. If docs/guides/foo.md exists, it will not get a menu entry.

So I guess the desired behaviour is that if a subfolder exists, we generate a page with a TOC for that subfolder and then each individual page within it. If no folder is found then we leave it as is. Is this correct?

[mcollina]

I think so, yes!

[jsumners]

Yes.