feat: adding ability to build docs (sidebar and toc) with generic script, small refactor to build-post-script

[boyney123]

Description

I'm currently working on #442 which allows us to pull down docs from external repos and render them on our website, a small part of that process the the ability to generate the needed .json file required for the side navigation and table of contents in the docs.

I started by writing my own file which you can see in #442, but after talking to @derberg we explored the ability to reuse what we already have.

This PR introduced and reuses what we already have to allow us to use this code more generically in the future.

Changes

• build-post-list.js is now build-doc-list.js
• the script now accepts arguments which allow us to make it more generic (also for use case https://github.com/asyncapi/website/pull/442).
• added .node-version file to tell Netlify which version of node to use when building, yargs won't work on super old version

New Arguments

• output - You can set the output of the file
• directory - You can specify the directory to process
• groupByCategories - This allows you to run the script and support the frontmatter format to group categories.

Grouping by front-matter

When groupByCategories is true, the front matter for the menu will be read and consumed. Here is an example

---
weight: 2
title: Installing Modelina
menu:
  docs:
    parent: 'Getting Started'
---

This example will render (in the sidebar):

• Getting Started
• • Modelina

At the moment the script relies on you having a _section.md file to group your docs (which is OK for a website, but https://github.com/asyncapi/website/pull/442 we want to make this abit more generic), and I want to give tool builders the ability to add docs without having to know about _section.md files and enforcing a folder structure on them too much. If they follow this standard markdown pattern they can render what they want on the website (under their tools url which needs to be decided still)

This solution allows people (from external tools) to group their docs without folders and _section.md format.

All they have to do is document the menu > docs > parent which will build the side navigation for them.

[netlify[bot]]

❌ Deploy Preview for asyncapi-website failed. Built without sensitive environment variables

🔨 Explore the source changes: 8c9d69fc2ce19eaf5013877c5322360f84f3e404

🔍 Inspect the deploy log: https://app.netlify.com/sites/asyncapi-website/deploys/618a8101712cfb000882d11a

[boyney123]

Thanks for the reviews.

I decided to look at this again, and I felt the code was bloating in areas, and I think it was time to separate some of the logic.

The new improvements are:

• new utils.js file (within the scripts dir to share some functions)
• new build-tools-list.js file which will be used later as part of the GitHub Actions process (for inserting external tools)
• edited build-docs-list.js just moved common code into the utils and kept it the same.

This will allow us to continue using build-docs-list as we were, but also use yargs in built-tools-list as I need to pass in arguments to build docs for particular tools.

Hopefully, that makes sense.

[quetzalliwrites]

The main issue I see here (if I am following correctly 😱), is the urls proposed?

So I wanted to give another explanation here of how you want to structure the urls for tools.

(First, remember that I'm talking to you about how I'm already planning on changing our docs main domain as well, so my examples below will make more sense.)

docs.asyncapi.com/tools/modelina

No subsections yet, cause one thing at a time.

Later, we can add/migrate the tools docs and create needed subsections.

[boyney123]

Thanks @alequetzalli

The main issue I see here (if I am following correctly 😱), is the URLs proposed?

Yeah at the moment this PR will extend what we have to get the docs onto the main website, but from what I'm reading maybe we should hold fire on this work until you have docs.asyncapi.com ready to go?

Sorry I'm not up to speed on whats happening with docs.asyncapi.com and the plans (maybe I've missed some threads etc)

[quetzalliwrites]

Yeah at the moment this PR will extend what we have to get the docs onto the main website, but from what I'm reading maybe we should hold fire on this work until you have docs.asyncapi.com ready to go?

IMHO, I think you are correct and that we should hold off on merging this one until the new URL redirects are in place. I am thinking I shall prioritize and do this the week after the conference because if I try to get it done before, I don't think Lukasz will have time to process my PRs. 😂😂😂

Sorry I'm not up to speed on whats happening with docs.asyncapi.com and the plans (maybe I've missed some threads etc)

Yes, you're totally right! Sorry about that, I noticed context was missing here.

I have created a Docs issue in our Docs Board to detail all the change implications from this URL cleanup I'm talking here: https://github.com/asyncapi/website/issues/459

[github-actions[bot]]

This pull request has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation.

There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: