docs: add sidebar #614

No mobile support.

Add a sidebar to the documentation pages. If you visit some page in the user documentation than the the user section is expanded and admin and contributors is collapsed.

Preview ready: https://forgejo.codeberg.page/@pull_614/
https://forgejo.codeberg.page/@pull_614/docs/next/user/actions/
https://forgejo.codeberg.page/@pull_614/docs/v12.0/user/actions/
https://forgejo.codeberg.page/@pull_614/docs/v12.0/user/actions/reference/
https://forgejo.codeberg.page/@pull_614/docs/next/user/actions/reference/
https://forgejo.codeberg.page/@pull_614/docs/v12.0/user/actions/basic-concepts/

Extremely useful: I frequently get lost.

Thanks, I'll have a look (with desktop) tomorrow or latest on Monday.

Can you rebase it, please? I'd like to see what it does to the new actions pages.

• text color on light scheme is wrong
• sidebar background is overlapping footer
• links are not working (likely a preview thing, but would be great if it works also there)
• packages and actions overview links are missing (because unclicklable in head of dropdown)
• sorting (currently using the slug) seems a bit unnatural, but could be improved in future versions
• also a bit more structure (like outlined in the index page of the user docs) would be nice, but could also go to future

If you visit some page in the user documentation than the the user section is expanded and admin and contributors is collapsed.

• at least in the preview this seems not working for me

image

@mahlzahn wrote in #614 (comment):

sorting (currently using the slug) seems a bit unnatural, but could be improved in future versions

Yeah this requires changes in the documentation files to specify their ordering via the frontmatter, so it matches the ordering of the associated index file.

@mahlzahn wrote in #614 (comment):

sidebar background is overlapping footer

Ah oh wow 🤦‍♀️ not sure how I missed that. I do now have another feature, for documentation pages where there's little content (such as /docs/latests) opening the dropdowns will push the footer down this seems unavoidable as you cannot specify the max-height to be that of a sibling element.

@mahlzahn wrote in #614 (comment):

links are not working (likely a preview thing, but would be great if it works also there)

Yeah, not really sure why this is happening as I am now using the correct functions to generate links :/

@mahlzahn wrote in #614 (comment):

packages and actions overview links are missing (because unclicklable in head of dropdown)

Once I am on the documentation for the 'next' version they show up for me:

image

@mahlzahn wrote in #614 (comment):

text color on light scheme is wrong

Ah did not check light mode 🙈

(削除) Hmm the preview is not being updated... (削除ここまで) Okay codeberg pages server caching.

21d3832e1b..c2ac4d5c1a makes the link work in preview.

😍 I'm informally approving based on visual testing alone. The code is beyond my paygrade.

image

@Gusted wrote in #614 (comment):

packages and actions overview links are missing (because unclicklable in head of dropdown)

Once I am on the documentation for the 'next' version they show up for me

I wasn't clear: There is no way to reach the

• https://forgejo.codeberg.page/@pull_614/docs/next/user/actions/overview/ and
• https://forgejo.codeberg.page/@pull_614/docs/next/user/packages/

from the new sidebar, because clicking on these items is unfolding the menu for the sub-items.

(Nice would be, if click on the title leads to the page and click on the down triangle opens the menu, but this doesn't work with the default <details> element, at least I didn't manage also in the context of Forgejo settings navigation.)

@mahlzahn wrote in #614 (comment):

(Nice would be, if click on the title leads to the page and click on the down triangle opens the menu, but this doesn't work with the default <details> element, at least I didn't manage also in the context of Forgejo settings navigation.)

This can quite easily be done, however I am not sure if we want to have some hover effect to indicate it's a link (that might be a bit unclear now).

c2ac4d5c1a..b31aa795da

@mahlzahn wrote in #614 (comment):

because clicking on these items is unfolding the menu for the sub-items

Not directly related, but since I noticed it in this preview: The same is true for the "Docs" link in the navbar. Since it becomes a dropdown now, the link back to the main docs page is gone.
The sidebar could get a link for that, though.

@Gusted wrote in #614 (comment):

This can quite easily be done, however I am not sure if we want to have some hover effect to indicate it's a link (that might be a bit unclear now).

That's pretty common, though. E.g. Read The Docs doesn't even show an indicator that something can be expanded until you click it (and load its corresponding page).

But are those pages even necessary? From what I can tell, most of them are just link collections anyways, which are effectively obsolete by the sidebar providing those same links.
So another option would be to move the few pages like /docs/next/user/packages/ to be another sub-item in the group. Then the group header wouldn't need to be a link.

Clicking/scrolling through the sidebar, I see a lot of verbose or redundant titles.

• The top-level sections all start with "Forgejo"
• The new pages for Actions all start with "Forgejo Actions"
• "Automatically Linked References in Issues, Pull Requests, and Commit Messages" takes three lines of text in the sidebar
• Every package registry page include "Package Registry"

I think the sidebar should support showing something other than the page title, and that many pages should fill out that "other" field to avoid those redundant titles.

I also think, the sidebar should get custom order and grouping similar to the link collection pages. The two modes that I could see users looking at the sidebar with are:

• Read from top to bottom, like the chapters of a book -> The order is all over the place (e.g. installing a runner comes before installing Forgejo), so there is no red thread of chapters to follow
• Read like a reference, looking for specific pages -> The order is all over the place, so you have to read through the entire list to find the page you want

It would require many small changes across all versions of the documentation, which should be done but I cannot commit to do that in a timely manner. The changes for the website would be very minimal once the documentation is updated to have that metadata.

@mahlzahn wrote in #614 (comment):

One issue, I see, is that now, when opening the documentation my whole attention is on the sidebar and I wonder if people will continue reading the structured index pages (for admin, user and contributor). What do you think about not expanding the sidebar items by default? Only, when the page is inside a submenu it should be expanded? I mean, e.g., when you are on the admin index page, then it the sidebar would be closed and only when you open a subpage it will expand.

I do not have a strong opinion on that, but I do see the usecase for it. I think for such smaller tweaks to the behavior would be better to receive feedback from several people about it. I am available to adjust this behavior after the fact.

@mahlzahn wrote in #614 (comment):

That is fixed now, thanks, minor nit: the highlighted (selected, current page) is not themed so well in light scheme. It should use the same color that is used on hovering (either pinkish or light greyish).

This should be fixed now, f9c20227ac..47d43d44c9.

It also includes the highlighting of collapsible pages and centers the caret icon.

I don't mean to destroy the work that has happened ... but would it make sense to reuse the structured index pages and extracting the custom order from there? They have been created anyway at the moment ...

I believe this PR is valuable in itself, and I would be in favour of merging it unconditionally.

To address the concerns raised here, it makes a lot of sense to do some other related changes. The summary pages are essentially a list of pages. The things missing are

1. external links
2. Sections without summary pages (e.g. "for translators")
3. Different link text than the actual title
4. Custom order

My take on the problems:

1. Get rid of external links. I have always been confused that they lead somewhere else than the docs.

2. Maybe allow nesting pages and somehow specifying an index name for it that is not rendered as an actual index page. Maybe by having frontmatter in a yaml file, an index file with only the frontmatter, or accepting that empty index pages can exist.

3. I believe that it makes some sense to adjust the page title in many cases. Let's think about the remaining problems afterwards. Maybe automatically include the parent title?

4. What about allowing an order prefix in the filenames that is stripped from the URL, if possible? So that we can have a structure like

   - 10-first-file
   - 20-second-file
   - 90-last-file
   

   which is rendered as

   • /first-file
   • /second-file
   • /last-file

Unless this suggestion can be implemented before the v12 release, I would be in favor of merging this as it is and work on improvements later. This makes the documentation much easier to navigate and having that when the v12 release is happening is good timing.

@fnetX wrote in #614 (comment):

but would it make sense to reuse the structured index pages and extracting the custom order from there? They have been created anyway at the moment ...

It makes sense to do so, but it's a time consuming task to do that across all versions of the documentation.

I am starting to move some pages. forgejo/docs#1326/ is the first part.