docs: add 2-level tabs, add examples and plugins, move comunity, split release notes #1345
Conversation
Performance Benchmark ResultsComparing PR changes against master branch: Benchmarks that have stayed the same:
|
| @@ -94,7 +94,7 @@ | |||
|
|
|||
| - Fix typo preventing benchmarking ([#1235](https://github.com/django-components/django-components/pull/1235)) | |||
|
|
|||
| ## 🚨📢 v0.140.0 | |||
| ## v0.140.0 🚨📢 | |||
There was a problem hiding this comment.
Moved those warning emojis after the version, so things are nicely aligned in the docs on index page and navigation
| ## 🚨📢 v0.110 | ||
| ## v0.110 🚨📢 | ||
|
|
||
| _25 Nov 2024_ |
There was a problem hiding this comment.
Added date to older releases. When the date is included, in the format like _25 Nov 2024_, then the script that prepares the Releases section in the documentation will pick up on these dates, and append them to the release page title, so e.g. v0.110.0 becomes v0.110.0 (2024-11-25).
| - "Documentation: Concepts": concepts | ||
| - "Documentation: API Reference": reference | ||
| - "Documentation: Guides": guides | ||
| - "Documentation: Upgrading": upgrading |
There was a problem hiding this comment.
Here you can see how to "2-level" tabs work - The section / tab name are actually like "Documentation: Concepts".
But when rendering the top navigation tabs, the trick I did was to split and group the tab names by prefixes. So all tabs that start with Documentation: will be stashed away under the Documentation top-level tab.
But in the remained of the app we still display these pages as they truly are, like "Documentation: Concepts". You can see that in the sidebar navigation, which have those full names:
| - Contributing: contributing.md | ||
| - Development: development.md | ||
| - Code of Conduct: code_of_conduct.md | ||
| - Dev Guides: devguides |
There was a problem hiding this comment.
All these sections were previously under Overview section, except for Dev guides, which were in Guides. I think this makes more sense, so that a new user doesn't have to go through all these when they are just trying to understand how the library works.
|
|
||
| ### Icons | ||
|
|
||
| - [djc-heroicons](https://pypi.org/project/djc-heroicons/) - Icons from HeroIcons.com for django-components. |
There was a problem hiding this comment.
My initial idea for the examples section was to be a place where we could put examplary component definitions (e.g. table, dialog, autocomplete, etc).
But in the documentation we've mentioned django-htmx-components and djc-heroicons. So instead of using that section solely for components, I decided to include also 3rd party libraries, grouped in some categories - similar to how you have the "awesome lists" on Github.
| @@ -1,5 +1,6 @@ | |||
| # `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav | |||
| nav: | |||
| - Installation: installation.md | |||
There was a problem hiding this comment.
Installation was moved as the first step of Getting started
Performance Benchmark ResultsComparing PR changes against master branch: Benchmarks that have stayed the same:
|
| {# This overrides the nav-item partial from mkdocs-material v9.6.17 #} | ||
| {# https://github.com/squidfunk/mkdocs-material/blob/c89a66bf39bb7f472e925753367ff8e464e0d683/src/templates/partials/nav-item.html #} | ||
| {# Majority of the file is the original, so our changes are highlighted #} | ||
| {# with `OUR CHANGES START` and `OUR CHANGES END` #} |
There was a problem hiding this comment.
As this comment says, this is an override for mkdocs-material, and 99% of the file remains the same, only the render_content() macro was modified.
It's a bit annoying that we have to copy the whole file just to make a small styling tweak. But I don't think (not aware at least) if there's a cleaner way to do this. Ideally we could specify to override only the render_content macro.
| </div> | ||
| </nav> | ||
|
|
||
| <script> |
There was a problem hiding this comment.
The script and style below are to make the opening of the sub-tabs smooth and cool. The behaviour is that:
- The sub-tabs will show when you hover over the top-level tab, and will hide again when you move cursor away.
- You can also click on the tab to ensure it remains open even after the cursor moves away. Second click closes it again.
Screen.Recording.2025-08-16.at.22.58.49.mov
Performance Benchmark ResultsComparing PR changes against master branch: Benchmarks that have stayed the same:
|
A lot of changes on the documentation site, so it can grow further:
2-level tabs navigation
I overrode how material theme (mkdocs-material) displays the tabs at the top of the page. Now, we can introduce a 2-levels of tabs:
When user hovers or clicks on the "Documentation" tab, instead of navigating to a page, a second level of tabs shows:
Collapsed:
Expanded:
I moved documentation related sections inside the umbrella "Documentation" tab, creating more space for other sections.
Some other sections which I can imagine being added in the future:
And this is how the 2-level tabs look in the sidebar navigation:
Examples section
Prepared a section where we can post examples or 3rd party components:
Community sections have own tab
With this, the "Overview" section got slimmer.
Installation moved to Gettings started
Release notes - each release has own page
I've made a script that parses the CHANGELOG and creates individual entries. Because some releases like v0.140 had tons of changes and huge write up on the release.