Use contextual sidebars

DocsPress normally renders one automatic sidebar from the synchronized WordPress Page tree. Keep that zero-configuration behavior for small and medium documentation sites. Add contextual sidebars only when distinct areas such as API reference, extensions, or CLI documentation need focused local navigation.

Start with the simple sidebar

Do not add sidebars-file when the complete documentation hierarchy belongs in one sidebar:

DocsPress continues to derive one nested Page tree from those files. Existing repositories receive no new metadata or navigation behavior unless they explicitly enable the advanced configuration.

Add a route registry

Create docs/sidebars.yml when the documentation has sections that should become independent navigation contexts:

version: 1default: docsShow annotation for line 21sidebars:  docs: .  api: apis  extensions: extensions

Then pass the repository-relative file to the Action:

- uses: Automattic/docspress@main  with:    wordpress-site: example.wordpress.com    wordpress-access-token: ${{ secrets.WP_ACCESS_TOKEN }}    docs-dir: docs    sidebars-file: docs/sidebars.ymlShow annotation for line 61    status: draft    dry-run: true

The DocsPress theme is required to render these contexts. Another theme can support the same feature by reading the synchronized _docspress_sidebar_id and _docspress_sidebar_root Page metadata.

Understand route matching

Sidebar roots are logical routes relative to docs-dir, not filesystem paths with extensions:

The registry follows four rules:

1. 1

   Name the default

   default must name one configured sidebar.

2. 2

   Keep the default at the root

   The default sidebar must use the root . route.

3. 3

   Resolve every focused route

   Each non-default root must match a real documentation route.

4. 4

   Let the most-specific route win

   A future apis/rest context can override apis for that subtree.

The same logical-route contract works with folder-derived Pages, manifest-file, and every tree produced by versions-file.

What changes on the site

On a Page assigned to a contextual sidebar, the DocsPress theme:

• starts automatic Docs Navigation at that sidebar's root Page;
• excludes Pages assigned to other sidebar IDs;
• scopes Adjacent Navigation so previous and next links cannot cross contexts;
• keeps the current Page, section collapse settings, Page order, and mobile drawer behavior intact.

Contextual sidebars do not change Command Search, the header Navigation block, or classic-menu mode. Search remains site-wide. Use an ordinary WordPress Navigation block for links that should remain available across every documentation context.

Copy the boilerplate

The repository includes a complete example under examples/contextual-sidebars:

The one-link demonstration is defined by theme/blueprint-sidebars.json. Maintainers can regenerate its deterministic Page fixture with:

npm run playground:sidebars

Return to one sidebar

Remove sidebars-file from the workflow to return to the original automatic Page tree.