Polykey-Docs: Non-Clickable Sidebar Category in Docusaurus Documentation

[CryptoTotalWar]

Requirements to close ticket

• [X] Achieve desired effect for getting started sidebar's structure
• [x] Update the gtag implementation referencing the latest directory name structures correctly
  • I investigated and was unable to find the cause of the issue to fix. A bug report is being made for this.

Is your feature request related to a problem? Please describe.

In the current setup of our Docusaurus-based documentation site, we face a limitation where categories in the sidebar are expected to link to a document or an automatically generated index page. This behavior necessitates that each category, including "Tutorials," is clickable and leads to a specific page. However, our design and user experience goals require the "Tutorials" category to solely act as a navigational container for its sub-pages without being linked to its own page. Attempts to remove the link or associate it with a README have led to build errors, indicating Docusaurus expects a document for navigation purposes.

Describe the solution you'd like

We aim to modify the sidebar behavior so that the "Tutorials" category remains visible and expandable/collapsible, allowing access to its sub-pages, but does not navigate to a separate page when clicked. Essentially, clicking on "Tutorials" should not redirect users but merely serve as a label for the subsections listed beneath it.

Target Behavior

Current behavior

The "Tutorials" category currently expands to show sub-pages, but we wish to disable its clickability while maintaining its role as a container.

Describe alternatives you've considered

Direct Removal: Initially attempted to remove the link from the sidebars.js configuration for the "Tutorials" category, which resulted in build failures due to missing document associations.

Placeholder Document: Thought of linking "Tutorials" to a placeholder or minimal README document. However, this approach contradicts our goal of having a purely navigational, non-clickable category.

Implementation Request

Seeking assistance in customizing the Docusaurus theme, specifically the sidebar component, to achieve a non-clickable "Tutorials" category. This customization should allow the category to remain interactive for revealing sub-pages without navigating away upon selection.

Technical Details

• Swizzling: Open to exploring swizzling the sidebar component for deeper customization.
• Custom Scripting: Considered adding custom JavaScript to prevent default click actions on the "Tutorials" category link, though this approach may not be sustainable or align with best practices.

Additional context

The documentation structure benefits significantly from having categories like "Tutorials" serve purely as organizational elements in the sidebar without contributing to the site's navigational paths. This adjustment enhances usability by clearly delineating between navigational labels and content pages.

[linear[bot]]

PRO-203 Polykey-Docs: Non-Clickable Sidebar Category in Docusaurus Documentation

[CryptoTotalWar]

Issue: when attempting to rename the Tutorials category label from "Tutorials" to "getting-started" we get the following error:

docs: [ { type: 'category', label: 'Tutorials', collapsed: false, link: { type: 'doc', id: 'tutorials/README', },

window.gtag is not a function
TypeError: window.gtag is not a function
    at eval (webpack-internal:///./node_modules/@docusaurus/plugin-google-gtag/lib/gtag.js:17:8)

  It might be a benign error and its related to how the Gtag was set-up. 

  But essentially the gtag expected the label "Tutorials" so renaming it to something else causes issues with Gtag. 

[CryptoTotalWar]

We're not going to deal with gtag issue for now.

Ed is going to see if we can use swizzle to customize the sidebar for the Tutorials -> renamed to Getting Started category as described here: https://www.phind.com/search?cache=kamxtl44c79n54yy8gvv2yyt

If Not, he may just create a label to simulate the container for getting started documentation pages.

[CryptoTotalWar]

We were able to achieve the desired results.

We were also able to add another sidebar item for the docs' entry page.

We're just missing to update the gtag information that is prompting warnings in development

[CryptoTotalWar]

https://github.com/MatrixAI/polykey.com/pull/45

This PR from Wen seems to reference implementation details with GTAG....

However, unsure if it is relecant to our error

window.gtag is not a function
TypeError: window.gtag is not a function
    at eval (webpack-internal:///./node_modules/@docusaurus/plugin-google-gtag/lib/gtag.js:17:8)

[CryptoTotalWar]

I don't think the error we are receiving above is related to any changes we made with our directory structure...

We're just going to have to make a separate ticket to investigate this problem and have Ed look into to try to fix.