Very long pages with no TOC

[setanarut]

Your Godot version: Godot 3.4.3 or Godot 4 alpha 4

Issue description: There are very long reference pages with no TOC. I have to use the search bar on the left first and then the browser's search bar to find what I'm looking for. Then It's easy to get lost in the huge pages.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_basics.html#classes

Github's auto-generated table of contents in the RST file. godotengine.org doesn't have this TOC.

https://user-images.githubusercontent.com/36481442/159352131-4b275e79-dccf-4740-a02c-b8e9512e3da9.mov

Enhancement request

1. As an alternative to the slow and cumbersome docs.godotengine.org site. Documents should be adapted to GitHub Flavored Markdown format and put on Github. So anyone who wants can fork and find what they're looking for.
2. or add TOC to the docs.godotengine.org. (My second reluctant choice.)

[Calinou]

As an alternative to the slow and cumbersome docs.godotengine.org site. Documents should be adapted to GitHub Flavored Markdown format and put on Github. So anyone who wants can fork and find what they're looking for.

In its early days (2014-2015), Godot used a GitHub wiki (with Markdown formatting) for its user documentation. It ended up being too limited, especially since note/warning blocks can't be created with just Markdown. There are nonstandard Markdown extensions that make this possible, but GitHub doesn't support rendering those.

The Sphinx RTD theme likely limits the number of levels that can be displayed in the sidebar, so I guess we need to add a manual table of contents at the top of long pages such as GDScript reference.

[setanarut]

It ended up being too limited, especially since note/warning blocks can't be created with just Markdown.

Note and warning boxes can be easily converted into quote blocks with a script. I even tried it and converted it. only links need to be rendered to relative links.

NOTE: Lorem ipsum dolor sit amet.

WARNING: Be realistic, demand the impossible!

---

so I guess we need to add a manual table of contents at the top of long pages such as GDScript reference.

It's useless if it's not one of the fixed menus in the corner like this;

https://user-images.githubusercontent.com/36481442/159363665-0e06931b-65b8-445d-b491-9e81bb2bd22b.mov

An real world example (no quotes in this example but can be added); https://github.com/vlang/v/blob/master/doc/docs.md

---

NOTE: Why do you prefer old-fashioned static site builders like Sphinx? There are faster and more modern technologies.

[ghost]

Can we re-open this please? This still seems to be an issue (limited levels in sidebar menu, and no TOC for pages (specifically GDScript Reference))...

[setanarut]

Can we re-open this please? This still seems to be an issue (limited levels in sidebar menu, and no TOC for pages (specifically GDScript Reference))...

ok

[tetrapod00]

https://github.com/godotengine/godot-docs/pull/9989 brought the GDScript reference page one level higher in the sidebar, so the page now has one level of header navigation in the sidebar:

In addtion to that, we can promote some of the existing headers slightly so that they appear in the sidebar navigation.

I'm not opposed to an actual TOC at the top of the page in addition to that, too.

[dalexeev]

@setanarut This isn't fixed yet, let's keep it open for now. We either need to add a table of contents/navigation or split the page into multiple pages for this issue to be considered fixed.