docs: Create a how-to guide section.

docs/async.md → docs/how-to/async.md

@@ -2,9 +2,9 @@
 
 htpy fully supports rendering HTML asynchronously. Combined with a async framework such as [Starlette/FastAPI](starlette.md), the entire web request can be processed async and the HTML page can be sent to the client incrementally as soon as it is ready.
 
-# Async components
+# Writing async components
 
-In addition to regular, [synchronous components](common-patterns.md), components can be defined as an `async def` coroutine. When rendering, htpy will `await` all async components:
+Components can be defined as an `async def` function. When rendering, htpy will `await` all async components:
 
 ```py
 from htpy import li

docs/django.md → docs/how-to/django.md

@@ -1,10 +1,8 @@
-# Usage With Django
+# Django
 
-htpy is not tied to any specific web framework. Nonetheless, htpy works great
-when combined with Django. This page contains information and useful techniques
-on how to combine htpy and Django.
+htpy works great with Django. This page contains information how you integrate htpy with Django.
 
-## Returning a htpy Response
+## Returning a htpy response from a Django view
 
 htpy elements can be passed directly to `HttpResponse`:
 
@@ -16,7 +14,7 @@ def my_view(request):
     return HttpResponse(html[body[div["Hi Django!"]]])
 ```
 
-## Using htpy as Part of an Existing Django Template
+## Using htpy as part of an existing Django template
 
 htpy elements are marked as "safe" and can be injected directly into Django
 templates. This can be useful if you want to start using htpy gradually in an
@@ -45,7 +43,7 @@ def index(request):
     })
 ```
 
-## Render a Django Form
+## Render a form
 
 CSRF token, form widgets and errors can be directly used within htpy elements:
 
@@ -108,9 +106,9 @@ def my_form_success_page() -> Renderable:
     )
 ```
 
-## Implement Custom Form Widgets With htpy
+## Implement custom form widgets
 
-You can implement a custom form widget directly with htpy like this:
+You can implement a custom form widget directly with htpy.
 
 ```py title="widgets.py"
 from django.forms import widgets
@@ -128,10 +126,10 @@ class ShoelaceInput(widgets.Widget):
         return str(sl_input(attrs, name=name, value=value))
 ```
 
-## The htpy Template Backend
+## Using htpy components directly from a template
 
-htpy includes a custom template backend. It makes it possible to use htpy
-instead of Django templates in places where a template name is required.  This
+htpy includes a custom template backend that makes it possible to use htpy
+instead of Django templates in places where a template name is required. This
 can be used with generic views or third party applications built to be used with
 Django templates.
 

docs/starlette.md → docs/how-to/starlette.md

@@ -1,9 +1,8 @@
-# Usage with Starlette/FastAPI
+# Starlette/FastAPI
 
-htpy can be used with Starlette to generate HTML. Since FastAPI is built upon Starlette, htpy can also be used with FastAPI.
-
-htpy supports full async rendering of all components. See [async rendering](async.md) for more information.
+htpy works great in combination with Starlette and FastAPI. htpy supports full async rendering of all components. See [async rendering](async.md) for more information.
 
+## Returning htpy content from a handler
 To return HTML contents, use the `HtpyResponse` class:
 
 ```py

mkdocs.yml

@@ -4,7 +4,6 @@ theme:
   name: material
   features:
     - content.code.copy
-    - toc.integrate
   palette:
     - media: "(prefers-color-scheme)"
       toggle:
@@ -25,11 +24,12 @@ theme:
 nav:
   - README.md
   - usage.md
+  - How-to guides:
+      - how-to/django.md
+      - how-to/async.md
+      - how-to/starlette.md
   - common-patterns.md
   - static-typing.md
-  - django.md
-  - async.md
-  - starlette.md
   - streaming.md
   - html2htpy.md
   - faq.md
@@ -55,4 +55,7 @@ markdown_extensions:
 plugins:
   - redirects:
       redirect_maps:
-        'changelog.md': 'https://github.com/pelme/htpy/releases'
+        "changelog.md": "https://github.com/pelme/htpy/releases"
+        async.md: how-to/async.md
+        django.md: how-to/django.md
+        starlette.md: how-to/starlette.md