refactor: use .nav.yml to define page order instead of nav weights (#1000)

docs/.nav.yml

@@ -0,0 +1,10 @@
+# For navigation content inspo see Pydantic https://docs.pydantic.dev/latest
+#
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - overview
+  - Getting Started: getting_started
+  - concepts
+  - guides
+  - API Documentation: reference
+  - Release Notes: release_notes.md

docs/SUMMARY.md

@@ -1,12 +0,0 @@
-<!-- See Pydantic for inspo https://docs.pydantic.dev/latest  -->
-- [Overview](overview/)
-- [Getting Started](getting_started/)
-- Concepts
-  - [Fundamentals](concepts/fundamentals/)
-  - [Advanced](concepts/advanced/)
-- Guides
-  - [Setup](guides/setup/)
-  - [Other](guides/other/)
-  - [Dev guides](guides/devguides/)
-- [API Documentation](reference/)
-- [Release notes](release_notes.md)

docs/concepts/.nav.yml

@@ -0,0 +1,4 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - fundamentals
+  - advanced

docs/concepts/advanced/.nav.yml

@@ -0,0 +1,11 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Rendering JS / CSS: rendering_js_css.md
+  - HTML fragments: html_fragments.md
+  - Prop drilling and provide / inject: provide_inject.md
+  - Lifecycle hooks: hooks.md
+  - Registering components: component_registry.md
+  - Typing and validation: typing_and_validation.md
+  - Custom template tags: template_tags.md
+  - Tag formatters: tag_formatter.md
+  - Authoring component libraries: authoring_component_libraries.md

docs/concepts/advanced/authoring_component_libraries.md

@@ -1,8 +1,3 @@
----
-title: Authoring component libraries
-weight: 9
----
-
 You can publish and share your components for others to use. Below you will find the steps to do so.
 
 For live examples, see the [Community examples](../../overview/community.md#community-examples).

docs/concepts/advanced/component_registry.md

@@ -1,8 +1,3 @@
----
-title: Registering components
-weight: 5
----
-
 In previous examples you could repeatedly see us using `@register()` to "register"
 the components. In this section we dive deeper into what it actually means and how you can
 manage (add or remove) components.

docs/concepts/advanced/hooks.md

@@ -1,8 +1,3 @@
----
-title: Lifecycle hooks
-weight: 4
----
-
 _New in version 0.96_
 
 Component hooks are functions that allow you to intercept the rendering process at specific positions.

docs/concepts/advanced/html_fragments.md

@@ -1,8 +1,3 @@
----
-title: HTML fragments
-weight: 2
----
-
 Django-components provides a seamless integration with HTML fragments ([HTML over the wire](https://hotwired.dev/)),
 whether you're using HTMX, AlpineJS, or vanilla JavaScript.
 

docs/concepts/advanced/provide_inject.md

@@ -1,8 +1,3 @@
----
-title: Prop drilling and provide / inject
-weight: 3
----
-
 _New in version 0.80_:
 
 Django components supports the provide / inject or ContextProvider pattern with the combination of:

docs/concepts/advanced/rendering_js_css.md

@@ -1,8 +1,3 @@
----
-title: Rendering JS / CSS
-weight: 1
----
-
 ### JS and CSS output locations
 
 If:

docs/concepts/advanced/tag_formatter.md

@@ -1,8 +1,3 @@
----
-title: Tag formatters
-weight: 8
----
-
 ## Customizing component tags with TagFormatter
 
 _New in version 0.89_

docs/concepts/advanced/template_tags.md

@@ -1,8 +1,3 @@
----
-title: Custom template tags
-weight: 7
----
-
 Template tags introduced by django-components, such as `{% component %}` and `{% slot %}`,
 offer additional features over the default Django template tags:
 

docs/concepts/advanced/typing_and_validation.md

@@ -1,8 +1,3 @@
----
-title: Typing and validation
-weight: 6
----
-
 ## Adding type hints with Generics
 
 _New in version 0.92_

docs/concepts/fundamentals/.nav.yml

@@ -0,0 +1,14 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Single-file components: single_file_components.md
+  - Components in Python: components_in_python.md
+  - Accessing component inputs: access_component_input.md
+  - Component context and scope: component_context_scope.md
+  - Template tag syntax: template_tag_syntax.md
+  - Slots: slots.md
+  - HTML attributes: html_attributes.md
+  - Defining HTML / JS / CSS files: defining_js_css_html_files.md
+  - Autodiscovery: autodiscovery.md
+  - Components as views: components_as_views.md
+  - HTTP Request: http_request.md
+  - Subclassing components: subclassing_components.md

docs/concepts/fundamentals/access_component_input.md

@@ -1,8 +1,3 @@
----
-title: Accessing component inputs
-weight: 3
----
-
 When you call `Component.render` or `Component.render_to_response`, the inputs to these methods can be accessed from within the instance under `self.input`.
 
 This means that you can use `self.input` inside:

docs/concepts/fundamentals/autodiscovery.md

@@ -1,8 +1,3 @@
----
-title: Autodiscovery
-weight: 9
----
-
 Every component that you want to use in the template with the [`{% component %}`](django_components.templateags.component_tags)
 tag needs to be registered with the [`ComponentRegistry`](django_components.component_registry.ComponentRegistry).
 Normally, we use the [`@register`](django_components.component_registry.register) decorator for that:

docs/concepts/fundamentals/component_context_scope.md

@@ -1,8 +1,3 @@
----
-title: Component context and scope
-weight: 4
----
-
 By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
 
 With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.

docs/concepts/fundamentals/components_as_views.md

@@ -1,8 +1,3 @@
----
-title: Components as views
-weight: 10
----
-
 _New in version 0.34_
 
 _Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested `Component.View` class_

docs/concepts/fundamentals/components_in_python.md

@@ -1,8 +1,3 @@
----
-title: Components in Python
-weight: 2
----
-
 _New in version 0.81_
 
 Components can be rendered outside of Django templates, calling them as regular functions ("React-style").

docs/concepts/fundamentals/defining_js_css_html_files.md

@@ -1,8 +1,3 @@
----
-title: Defining HTML / JS / CSS files
-weight: 8
----
-
 As you could have seen in [the tutorial](../../getting_started/adding_js_and_css.md), there's multiple ways how you can associate
 HTML / JS / CSS with a component:
 

docs/concepts/fundamentals/html_attributes.md

@@ -1,8 +1,3 @@
----
-title: HTML attributes
-weight: 7
----
-
 _New in version 0.74_:
 
 You can use the `html_attrs` tag to render HTML attributes, given a dictionary

docs/concepts/fundamentals/http_request.md

@@ -1,8 +1,3 @@
----
-title: HTTP Request
-weight: 11
----
-
 The most common use of django-components is to render HTML for a given request. As such,
 there are a few features that are dependent on the request object.
 

docs/concepts/fundamentals/single_file_components.md

@@ -1,8 +1,3 @@
----
-title: Single-file components
-weight: 1
----
-
 Components can be defined in a single file, which is useful for small components. To do this, you can use the `template`, `js`, and `css` class attributes instead of the `template_file`, `js_file`,  and `css_file`.
 
 For example, here's the calendar component from

docs/concepts/fundamentals/slots.md

@@ -1,8 +1,3 @@
----
-title: Slots
-weight: 6
----
-
 _New in version 0.26_:
 
 - The `slot` tag now serves only to declare new slots inside the component template.

docs/concepts/fundamentals/subclassing_components.md

@@ -1,8 +1,3 @@
----
-title: Subclassing components
-weight: 12
----
-
 In larger projects, you might need to write multiple components with similar behavior.
 In such cases, you can extract shared behavior into a standalone component class to keep things
 [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).

docs/concepts/fundamentals/template_tag_syntax.md

@@ -1,8 +1,3 @@
----
-title: Template tag syntax
-weight: 5
----
-
 All template tags in django_component, like `{% component %}` or `{% slot %}`, and so on,
 support extra syntax that makes it possible to write components like in Vue or React (JSX).
 

docs/getting_started/.nav.yml

@@ -0,0 +1,7 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Create your first component: your_first_component.md
+  - Adding JS and CSS: adding_js_and_css.md
+  - Components in templates: components_in_templates.md
+  - Parametrising components: parametrising_components.md
+  - Adding slots: adding_slots.md

docs/getting_started/adding_js_and_css.md

@@ -1,8 +1,3 @@
----
-title: Adding JS and CSS
-weight: 2
----
-
 Next we will add CSS and JavaScript to our template.
 
 !!! info

docs/getting_started/adding_slots.md

@@ -1,8 +1,3 @@
----
-title: Adding slots
-weight: 5
----
-
 Our calendar component's looking great! But we just got a new assignment from
 our colleague - The calendar date needs to be shown on 3 different pages:
 

docs/getting_started/components_in_templates.md

@@ -1,8 +1,3 @@
----
-title: Components in templates
-weight: 3
----
-
 By the end of this section, we want to be able to use our components in Django templates like so:
 
 ```htmldjango

docs/getting_started/parametrising_components.md

@@ -1,8 +1,3 @@
----
-title: Parametrising components
-weight: 4
----
-
 So far, our Calendar component will always render the date `1970-01-01`. Let's make it more useful and flexible
 by being able to pass in custom date.
 

docs/getting_started/your_first_component.md

@@ -1,8 +1,3 @@
----
-title: Create your first component
-weight: 1
----
-
 A component in django-components can be as simple as a Django template and Python code to declare the component:
 
 ```htmldjango title="calendar.html"

docs/guides/.nav.yml

@@ -0,0 +1,5 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - setup
+  - other
+  - Dev Guides: devguides

docs/guides/devguides/.nav.yml

@@ -0,0 +1,5 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - JS and CSS rendering: dependency_mgmt.md
+  - Slot rendering: slot_rendering.md
+  - Using slot and block tags: slots_and_blocks.md

docs/guides/devguides/slot_rendering.md

@@ -1,5 +1,3 @@
-# Slot rendering
-
 This doc serves as a primer on how component slots and fills are resolved.
 
 ## Flow

docs/guides/devguides/slots_and_blocks.md

@@ -1,5 +1,3 @@
-# Using `slot` and `block` tags
-
 1.  First let's clarify how `include` and `extends` tags work inside components.
 
     When component template includes `include` or `extends` tags, it's as if the "included"

docs/guides/other/.nav.yml

@@ -0,0 +1,3 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Troubleshooting: troubleshooting.md

docs/guides/other/troubleshooting.md

@@ -1,8 +1,3 @@
----
-title: Troubleshooting
-weight: 1
----
-
 As larger projects get more complex, it can be hard to debug issues. Django Components provides a number of tools and approaches that can help you with that.
 
 ## Component and slot highlighting

docs/guides/setup/.nav.yml

@@ -0,0 +1,5 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Syntax highlighting: syntax_highlight.md
+  - Caching: caching.md
+  - Development server: development_server.md

docs/guides/setup/caching.md

@@ -1,8 +1,3 @@
----
-title: Caching
-weight: 2
----
-
 This page describes the kinds of assets that django-components caches and how to configure the cache backends.
 
 ## Component's JS and CSS files

docs/guides/setup/development_server.md

@@ -1,8 +1,3 @@
----
-title: Development server
-weight: 3
----
-
 ### Reload dev server on component file changes
 
 This is relevant if you are using the project structure as shown in our examples, where

docs/guides/setup/syntax_highlight.md

@@ -1,8 +1,3 @@
----
-title: Syntax highlighting
-weight: 1
----
-
 ## VSCode
 
 1. First install [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.

docs/overview/.nav.yml

@@ -0,0 +1,12 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - Welcome to Django Components: welcome.md
+  - Compatibility: compatibility.md
+  - Installation: installation.md
+  - Security notes 🚨: security_notes.md
+  - Community: community.md
+  - Contributing: contributing.md
+  - Development: development.md
+  - Performance: performance.md
+  - Code of Conduct: code_of_conduct.md
+  - License: license.md

docs/overview/code_of_conduct.md

@@ -1,6 +1 @@
----
-title: Code of Conduct
-weight: 9
----
-
 --8<-- "CODE_OF_CONDUCT.md"

docs/overview/community.md

@@ -1,8 +1,3 @@
----
-title: Community
-weight: 5
----
-
 ## Community questions
 
 The best place to ask questions is in our [Github Discussion board](https://github.com/django-components/django-components/discussions).

docs/overview/compatibility.md

@@ -1,9 +1,3 @@
----
-title: Compatibility
-weight: 2
----
-## Compatibility
-
 Django-components supports all supported combinations versions of [Django](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django) and [Python](https://devguide.python.org/versions/#versions).
 
 | Python version | Django version |

docs/overview/contributing.md

@@ -1,8 +1,3 @@
----
-title: Contributing
-weight: 6
----
-
 ### Bug reports
 
 If you find a bug, please open an issue with detailed description of what happened.

docs/overview/development.md

@@ -1,8 +1,3 @@
----
-title: Development
-weight: 7
----
-
 ## Install locally and run the tests
 
 Start by forking the project by clicking the **Fork button** up in the right corner in the [GitHub](https://github.com/django-components/django-components).

docs/overview/installation.md

@@ -1,8 +1,3 @@
----
-title: Installation
-weight: 3
----
-
 1. Install `django_components` into your environment:
 
     ```bash

docs/overview/license.md

@@ -1,6 +1 @@
----
-title: License
-weight: 10
----
-
 --8<-- "LICENSE"

docs/overview/performance.md

@@ -1,8 +1,3 @@
----
-title: Performance
-weight: 8
----
-
 We track the performance of `django-components` using [ASV](https://asv.readthedocs.io/en/stable/).
 
 See the [benchmarks dashboard](../../benchmarks).

docs/overview/security_notes.md

@@ -1,8 +1,3 @@
----
-title: Security notes 🚨
-weight: 4
----
-
 _It is strongly recommended to read this section before using django-components in production._
 
 ## Static files

docs/overview/welcome.md

@@ -1,8 +1,3 @@
----
-title: Welcome to Django Components
-weight: 1
----
-
 <img src="https://raw.githubusercontent.com/django-components/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
 
 [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml)

docs/reference/.nav.yml

@@ -0,0 +1,13 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+  - API: api.md
+  - Commands: commands.md
+  - Components: components.md
+  - Exceptions: exceptions.md
+  - Middlewares: middlewares.md
+  - Settings: settings.md
+  - Signals: signals.md
+  - Tag formatters: tag_formatters.md
+  - Template tags: template_tags.md
+  - Template vars: template_vars.md
+  - URLs: urls.md

mkdocs.yml

@@ -20,8 +20,6 @@ watch:
   - scripts
 
 validation:
-  # We get warnings as we use literate-nav
-  omitted_files: ignore
   absolute_links: warn
   unrecognized_links: info
 
@@ -125,9 +123,7 @@ plugins:
       scripts:
         - docs/scripts/setup.py
         - docs/scripts/reference.py
-  - literate-nav:
-      nav_file: SUMMARY.md
-      tab_length: 2
+  - awesome-nav
   - git-revision-date-localized:
       enabled: !ENV [CI, false]
       type: timeago
@@ -144,7 +140,6 @@ plugins:
         - code_of_conduct.md
         - license.md
   - markdown-exec
-  - mkdocs-nav-weight
   # - toc-md:
   - search
   - social:

pyproject.toml

@@ -142,6 +142,7 @@ dependencies = [
     "black",
     "pygments",
     "pygments-djc",
+    "mkdocs-awesome-nav",
 ]
 
 [tool.hatch.env.collectors.mkdocs.docs]

requirements-docs.txt

@@ -5,15 +5,14 @@
 # - mike
 # - mkdocs
 # - mkdocs-autorefs
+# - mkdocs-awesome-nav
 # - mkdocs-gen-files
 # - mkdocs-git-authors-plugin
 # - mkdocs-git-revision-date-localized-plugin
 # - mkdocs-include-markdown-plugin
-# - mkdocs-literate-nav
 # - mkdocs-material
 # - mkdocs-material[imaging]
 # - mkdocs-minify-plugin
-# - mkdocs-nav-weight
 # - mkdocs-redirects
 # - mkdocstrings
 # - mkdocstrings-python
@@ -113,14 +112,13 @@ mkdocs==1.6.1
     #   hatch.envs.docs
     #   mike
     #   mkdocs-autorefs
+    #   mkdocs-awesome-nav
     #   mkdocs-gen-files
     #   mkdocs-git-authors-plugin
     #   mkdocs-git-revision-date-localized-plugin
     #   mkdocs-include-markdown-plugin
-    #   mkdocs-literate-nav
     #   mkdocs-material
     #   mkdocs-minify-plugin
-    #   mkdocs-nav-weight
     #   mkdocs-redirects
     #   mkdocstrings
 mkdocs-autorefs==1.3.1
@@ -128,6 +126,8 @@ mkdocs-autorefs==1.3.1
     #   hatch.envs.docs
     #   mkdocstrings
     #   mkdocstrings-python
+mkdocs-awesome-nav==3.0.0
+    # via hatch.envs.docs
 mkdocs-gen-files==0.5.0
     # via hatch.envs.docs
 mkdocs-get-deps==0.2.0
@@ -140,16 +140,12 @@ mkdocs-git-revision-date-localized-plugin==1.3.0
     # via hatch.envs.docs
 mkdocs-include-markdown-plugin==7.1.4
     # via hatch.envs.docs
-mkdocs-literate-nav==0.6.1
-    # via hatch.envs.docs
 mkdocs-material==9.6.4
     # via hatch.envs.docs
 mkdocs-material-extensions==1.3.1
     # via mkdocs-material
 mkdocs-minify-plugin==0.8.0
     # via hatch.envs.docs
-mkdocs-nav-weight==0.2.0
-    # via hatch.envs.docs
 mkdocs-redirects==1.2.2
     # via hatch.envs.docs
 mkdocstrings==0.28.1