fix: Implement a TOC component

[techmannih]

What kind of change does this PR introduce?
This PR introduces a new Table of Contents (TOC) component to improve the navigation within long documentation pages. It parses the markdown content and dynamically generates a list of links to the headers, making it easier for users to navigate the page

Issue Number:

• Closes [📝 Docs]: Implement a TOC component #1109

[techmannih]

@valeriahhdez @Kalevins
We need to discuss the documentation sections for the following endpoints:

/implementers/interfaces
/understanding-json-schema/reference/annotations
/understanding-json-schema/reference/comments
/understanding-json-schema/reference/enum
/understanding-json-schema/reference/const
/understanding-json-schema/reference/null
/understanding-json-schema/reference/boolean
/understanding-json-schema/reference/type

Currently, there is no heading for these sections in the docs. Also, for the Table of Contents (TOC), can we include the titles of the page sections, or is there a better way to organize them? Let’s discuss how we can improve the structure and add appropriate headings and TOC elements.

[techmannih]

@valeriahhdez Please review this PR

[valeriahhdez]

Hi @techmannih,

I'm not sure I understand what you mean by "there's no heading for these sections in the docs". Can you please expand on that?

[techmannih]

@valeriahhdez I mean, for these points, there is no heading and content available that can be added in TOC. In toc, we are adding heading

[valeriahhdez]

Summary of our Slack discussion:

• The endpoints' content lacks headings and therefore the TOC is empty when generated.
• The documentation team will edit this documentation and reorganize its content by headings. This will improve the readers' experience by making it easier to scan and find information.
• Editing the documentation is outside the scope of this PR, so we will create a separate issue for the task.

[valeriahhdez]

Hi @DhairyaMajmudar, can you please help us review this PR?

[DhairyaMajmudar]

@techmannih pls. fix the failing ci

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	870ce15

[techmannih]

@DhairyaMajmudar, I have fixed the lint errors. Only the type-checking workflow is still giving an error.

[benjagm]

Hi @techmannih . At first look, it seems that you are repeating the same structure again and again in all pages, all with a lot of repeated code an static code. This is a typical scenario where is better to think about creating a standard component to make all this process much easier.

Check for the Layout.tsx component used to build the layouts. Maybe you can do this by default there.

What do you think?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (8676fc2) to head (870ce15).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1127   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          373       373           
  Branches        94        94           
=========================================
  Hits           373       373           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[techmannih]

Yes @benjagm , I am following the previous TOC that was built for the blog pages. Please check this one.

And yes, I am using "on this page" in a static manner, which is being resolved now. I think you might have seen this in a static way because there are a lot of files, and each section has a separate YAML file. For blog pages, there's only one file, and all the YAML files are rendered within it.

But for the documentation, we are using separate files for each section. The TOC is already created; as per my understanding, I am just integrating it into each section

[benjagm]

I am following the previous TOC that was built for the blog pages. Please check this one.

My expectation with this PR is to avoid having to add the TOC to every single page. Instead, it would be great having it generated automatically at the layout level the same way we have the sidebar automatically generated.

[benjagm]

My expectation with this PR is to avoid having to add the TOC to every single page. Instead, it would be great having it generated automatically at the layout level the same way we have the sidebar automatically generated.

[techmannih]

@benjagm Absolutely agree! Having the TOC automatically generated at the layout level would save a lot of time and ensure consistency. I will implement

[benjagm]

H i @techmannih . How is it going with the requested changes? Do you need help or advice?