Vertical Sidebar Navigation

A WordPress plugin that adds a Vertical Sidebar block style to the core/navigation block, with hierarchical disclosure, automatic open-path-to-current-page, and a mobile push-down hamburger that does not overlay content.

What it does

• Single block style on core/navigation — no custom block, no Inspector additions.
• Block-theme (FSE) only. Refuses to activate on classic themes.
• Hierarchical disclosure: only the top level is visible by default; children expand on click.
• Auto-open of the current path: deep pages open their ancestor chain automatically.
• Mobile push-down hamburger: below the breakpoint, the navigation collapses into a burger button that expands in place — no off-canvas overlay.
• Themeable via --vsn-* CSS custom properties. No hard-coded colours.

Requirement for interactive toggling: set the navigation block's submenu setting to open on click (labelled "Open submenus on click", or "Submenu visibility → On click" in newer WordPress). On click, parents are toggle buttons and several submenus can stay open at once (Pattern B) — but the parent's own page is no longer reachable from the menu (core WordPress behaviour). On hover, parents stay links (page reachable); nothing toggles on click and only the auto-open path to the current page is shown — a single open branch that can look like an accordion even though accordion mode is off (Pattern A).

See readme.txt for the full user-facing documentation (FAQ, theme-integration snippet, CSS-variable reference).

Development

Prerequisites

• PHP 8.1+ (the plugin runs on 7.4+; dev tooling requires 8.1)
• Node 20+
• Composer 2
• Docker (for wp-env)

Setup

composer install
npm install

Lint everything

composer run lint   # PHPCS
npm run lint        # ESLint + Stylelint + Markdownlint

Run E2E tests

npx wp-env start
npm run test:e2e

Plugin Check (pre-WP.org-submission)

npx wp-env start
npm run plugin-check

Build distribution ZIP

npm run build:zip        # = bash bin/build-zip.sh

Output location (in order of precedence): $OUTPUT_DIR if set → the sibling ../../Builds/ folder if it exists (workspace setup) → otherwise build/ (CI fallback). The file is named vertical-sidebar-navigation-<version>.zip, where <version> is read from the plugin header / Stable tag (both are cross-checked).

Releasing

1. Bump the version in vertical-sidebar-navigation.php (header + VSN_VERSION) and readme.txt (Stable tag).
2. Update == Changelog == and == Upgrade Notice == in readme.txt.
3. Commit and tag: git tag v<version> && git push origin main --tags.
4. The release.yml workflow verifies version consistency, builds the ZIP, and publishes a GitHub Release with the ZIP attached.

Contributing

See CONTRIBUTING.md.

License

GPL-2.0-or-later. See LICENSE.