wookie184
commented
5 months ago This is a great idea, and would be really useful for things like the contributing section as you mention.
I do think that the category pages changes would be out of scope for this. It's already a pretty big task, and there are potentially also other things to consider w.r.t category pages, since I think going More->content from the main page to get a jumbled list of things is another issue and could potentially do with a bigger rethink in how individual sub-sections are accessed.
hedyhli
We have some high-quality articles over at
/pages/and I look forward to seeing more. However, as someone who has a fairly sound grasp of the organization and structure of the content as compared to a new user, I still struggle to navigate and discover more pages with ease. I often find myself stumbling upon pages I have not seen years before (despite themselves being present) as well as having troubles recalling the hierarchies of the content when needing to link a page to someone on the server.I believe it's possible to improve the situation by adding a left column that displays the tree of links representing the hierarchy of content pages - siblings, parents, children (not the headings of the page).
Mock implementation
What we have currently
The breadcrumb at the top of each page lets you jump to one of the parent pages. It's great to know where you are and what else is there higher up the hierarchy, however it doesn't make it easy to directly browse exactly what else is there and visit those pages.
The sub-articles dropdown lets you see the pages under the current page and jump to one of them, but it feels clunky to use and is not very discoverable. Compare this to something like readthedocs themes, Mkdocs themes, the left column is almost impossible to miss, and it easily becomes your main source of discovery for new pages of interest.
Our contributing pages have a lot of sub-pages with valuable information that is very easy to be missed. Some of the sub-pages even have sub-pages of their own. For someone trying to find their way around making contributions to our repositories, it could be daunting to look at the dropdown and not know which page they might need. Each time they finish reading a sub-article they would have to go back to the preview page before attempting to find the right position of the previously visited sub-article, and finally click on the next link. I have experienced this inconvenience personally and I'm sure many new users would go through a similar process.
All this can be improved significantly with the introduction of better navigation component commonly found in documentation websites.
Co-existing with the ToC column
The column for table of contents on the right is great, it's optionally enabled based on the article metadata. Introducing another column on the left of the content alongside the table of contents is still possible.
On screens with a width of a relatively wide laptop or higher
The current reading experience is not super decent. The number of characters in a single line can go up to more than 180! We want to provide good readability for articles that are meant to be read. Adding a navigation column on the left in addition to having the ToC column would not affect these wider viewports at all. In fact, it would improve the readability.
On smaller laptops & tablets
The sidebar can be hidden behind a toggle. When visible, it squishes the main content so that the content is still readable, but might be too narrow for some readers, so for them the sidebar can be hidden by default when reading. There is no need to use a modal for this screen size IMO.
On mobile or vertical screens
The sidebar is visible only after a click on a button, which would display the menu on top of the content. Or in such a way that the normal content is not visible at all. [ReadTheDocs example for mobile]
Modal sidebar example
[🔗](https://goreleaser.com/customization/env/)https://github.com/python-discord/site/assets/50042066/6fe9ecb9-b1f0-492a-a66e-714d9e01daac
The screencast above illustrates the distinction between toggle of visibility that squishes main content verses one that covers the main content.
And what about category pages?
While the box shadows and title icons for the category listings makes the category pages clear and appealing, it can also benefit from a makeover that makes use of tree-like navigation. Unlike GitHub, we don't have a lot of tabular information like last commit dates to show.
An example of this in action
The categories can be toggled to collapse pages under it, with each category page showing the direct children by default, all other pages are hidden until toggled.
We could also just show the same sidebar as those on normal pages, just like GitHub does for directories.
This can make use of a reusable component defined for the sidebar used on content pages.
One might argue it's out of scope for this issue, so I'll leave this up to discussion and for the one who implements this feature.
The specifics
An ideal implementation might look something like the following (note that these are only ideas and is still up to discussion).
Compute the hierarchy of all content pages on site startup, just once. This data structure should allow for selecting a sub-structure for a specified category or page.
When rendering a page, use something like a dictionary to set the current slug to be "highlighted", or some other form of data to be passed to the template when rendering. (Note that we already know the parents for a page through
PageOrCategoryView.location.parents)Each page can add a metadata entry to specify the slug of the highest level parent to be shown in the hierarchy.
For example, we might want all pages in PyDis guides to have the highest level being PyDis guides. Contributing pages to use the primary contributing page as the highest (see the mock implementation screenshot at the top, where the highest level is the contributing page).
This is done to remove unnecessary clutter and indentation in the sidebar based on the scope of the page. Although once we have a prototype we might realize there is no such need to limit the highest level at all. (See Appendix)
In the template for each page, render the hierarchy and apply a class to the currently highlighted item for it to be indicated as current page.
Categories shown in the tree will only be dropdowns with their appropriate icons. Articles with sub-articles would also have links in addition to being dropdowns.
Each category page can show the tree starting from the current category. This can be kept for backwards compatibility but we don't need to link to them in the sidebar for article pages.
All top-level dropdowns will be unexpanded by default except the one that leads to the current page. Unless this is too hard to implement we can expand all for the initial implementation and improve it in the future. (See Appendix)
More examples
Consider these only for inspiration:
Appendix
These are only for reference to gauge the approximate length and maximum indent level for a tree.
A fully expanded tree for all content pages
``` . ├── _info.yml ├── code-of-conduct.md ├── frequently-asked-questions.md ├── guides │ ├── _info.yml │ ├── pydis-guides │ │ ├── _info.yml │ │ ├── asking-good-questions.md │ │ ├── code-reviews-primer.md │ │ ├── contributing │ │ │ ├── _info.yml │ │ │ ├── bot-extended-configuration-options.md │ │ │ ├── bot.md │ │ │ ├── cloning-repository.md │ │ │ ├── commit-messages.md │ │ │ ├── configure-environment-variables.md │ │ │ ├── contributing-guidelines.md │ │ │ ├── creating-bot-account.md │ │ │ ├── docker.md │ │ │ ├── forking-repository.md │ │ │ ├── hosts-file.md │ │ │ ├── installing-project-dependencies.md │ │ │ ├── issues.md │ │ │ ├── linting.md │ │ │ ├── logging.md │ │ │ ├── obtaining-discord-ids.md │ │ │ ├── pull-requests.md │ │ │ ├── setting-test-server-and-bot-account.md │ │ │ ├── sir-lancebot │ │ │ │ ├── _info.yml │ │ │ │ └── env-var-reference.md │ │ │ ├── sir-lancebot.md │ │ │ ├── site.md │ │ │ ├── style-guide.md │ │ │ ├── working-with-git │ │ │ │ ├── _info.yml │ │ │ │ ├── cli.md │ │ │ │ └── pycharm.md │ │ │ └── working-with-git.md │ │ ├── contributing.md │ │ ├── help-channel-guide.md │ │ ├── helping-others.md │ │ ├── how-to-contribute-a-page.md │ │ └── off-topic-etiquette.md │ └── python-guides │ ├── _info.yml │ ├── app-commands.md │ ├── creating-python-environment-windows.md │ ├── discord-embed-limits.md │ ├── discord-messages-with-colors.md │ ├── discordpy-subclassing-context.md │ ├── discordpy.md │ ├── discordpy_help_command.md │ ├── docker-hosting-guide.md │ ├── fix-ssl-certificate.md │ ├── keeping-tokens-safe.md │ ├── mutability.md │ ├── parameters-and-arguments.md │ ├── proper-error-handling.md │ ├── setting-different-statuses-on-your-bot.md │ ├── subclassing_bot.md │ ├── vps-services.md │ └── why-not-json-as-database.md ├── privacy.md ├── rules.md ├── security-notice.md ├── server-info │ ├── _info.yml │ ├── roles.md │ └── staff-role-expectations.md └── tags └── _info.yml ```A fully expanded tree for all contributing pages
``` . ├── _info.yml ├── bot-extended-configuration-options.md ├── bot.md ├── cloning-repository.md ├── commit-messages.md ├── configure-environment-variables.md ├── contributing-guidelines.md ├── creating-bot-account.md ├── docker.md ├── forking-repository.md ├── hosts-file.md ├── installing-project-dependencies.md ├── issues.md ├── linting.md ├── logging.md ├── obtaining-discord-ids.md ├── pull-requests.md ├── setting-test-server-and-bot-account.md ├── sir-lancebot │ ├── _info.yml │ └── env-var-reference.md ├── sir-lancebot.md ├── site.md ├── style-guide.md ├── working-with-git │ ├── _info.yml │ ├── cli.md │ └── pycharm.md └── working-with-git.md ```