docs: improve documentation for package docs

docs/src/content/docs/guides/publishing.mdx

@@ -3,7 +3,7 @@ title: Publishing Packages
 description: Learn how to publish packages to the pesde registry.
 ---
 
-import { LinkCard } from "@astrojs/starlight/components"
+import { Aside, LinkCard } from "@astrojs/starlight/components"
 
 ## Configuration
 
@@ -58,7 +58,8 @@ build_files = ["src"]
 
 ## Authentication
 
-Before you can publish a package, you must authenticate with your GitHub account.
+Before you can publish a package, you must authenticate with your GitHub
+account.
 
 ```sh
 pesde auth login
@@ -96,5 +97,41 @@ environment.
 The `README.md` file in the root of the package will be displayed on the
 [pesde registry website](https://pesde.daimond113.com/).
 
-If you have a `docs` directory in the root of the package, they will be
-hosted by pesde and be accessible on the pesde website.
+You can include a `docs` directory in the package containing markdown files
+and they will be available on the pesde registry website. You can see an example
+in [`pesde/hello`](https://pesde.daimond113.com/packages/pesde/hello/latest/any/docs).
+
+### Customizing the sidebar
+
+You can include frontmatter with a `sidebar_position` to customize the order
+of the pages on the sidebar.
+
+```md title="docs/getting-started.md"
+---
+sidebar_position: 2
+---
+
+# Getting Started
+
+Lorem ipsum odor amet, consectetuer adipiscing elit. Eleifend consectetur id
+consequat conubia fames curae?
+```
+
+You can have directories in the `docs` directory to create nested pages. These
+will show up as collapsible sections in the sidebar. You can include a
+`_category_.json` file inside the nested directories to customize the label and
+the ordering in the sidebar.
+
+```json title="docs/guides/_category_.json"
+{
+	"label": "Guides",
+	"position": 3
+}
+```
+
+<Aside type="tip">
+
+Make sure to include `docs` inside the `includes` field in `pesde.toml`
+otherwise they won't be published with your package.
+
+</Aside>