From 5fdeec57b586c4a17f805daf6b9a3e7ace68592b Mon Sep 17 00:00:00 2001 From: Sohilbhai Ghanchivahora Date: Fri, 23 Jan 2026 17:46:06 +0530 Subject: [PATCH] Updated wp sidebar command doc- using content, example, resources --- commands/sidebar.md | 191 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 183 insertions(+), 8 deletions(-) diff --git a/commands/sidebar.md b/commands/sidebar.md index 378dc57d..831c5234 100644 --- a/commands/sidebar.md +++ b/commands/sidebar.md @@ -1,15 +1,190 @@ # wp sidebar -Lists registered sidebars. +Lists registered sidebars in WordPress. -A [sidebar](https://developer.wordpress.org/themes/functionality/sidebars/) is any widgetized area of your theme. +## Description -### EXAMPLES +A [sidebar](https://developer.wordpress.org/themes/functionality/sidebars/) is any widgetized area of your theme where widgets can be placed and displayed. Sidebars are typically used for features like: - # List sidebars - $ wp sidebar list --fields=name,id --format=csv - name,id - "Widget Area",sidebar-1 - "Inactive Widgets",wp_inactive_widgets +- Navigation menus +- Recent posts widgets +- Category listings +- Search boxes +- Custom content areas +- Footer content regions +The `wp sidebar` command provides tools to inspect, manage, and query the sidebars registered in your WordPress installation, whether they are active or inactive. +## Subcommands + +### wp sidebar list + +Lists all registered sidebars on your site. + +#### Options + +| Option | Description | Type | Default | +|--------|-------------|------|---------| +| `--fields` | Limit the output to specific fields (e.g., `name,id,description`) | string | all | +| `--format` | Render output in a specific format (`table`, `csv`, `json`, `count`) | string | table | +| `--exclude-inactive` | Exclude inactive sidebar areas | boolean | false | +| `--search` | Search sidebars by name | string | none | + +#### Common Fields + +- **name**: The human-readable name of the sidebar +- **id**: The unique identifier for the sidebar +- **description**: A brief description of the sidebar +- **class**: CSS class assigned to the sidebar +- **before_widget**: HTML markup before each widget in the sidebar +- **after_widget**: HTML markup after each widget in the sidebar +- **before_title**: HTML markup before widget titles +- **after_title**: HTML markup after widget titles + +## Examples + +### List all sidebars with name and ID + +```bash +$ wp sidebar list --fields=name,id ++-----------------+-----------------+ +| name | id | ++-----------------+-----------------+ +| Widget Area | sidebar-1 | +| Inactive Widgets| wp_inactive_widgets | ++-----------------+-----------------+ +``` + +### Export sidebars as CSV + +```bash +$ wp sidebar list --fields=name,id --format=csv +name,id +"Widget Area",sidebar-1 +"Inactive Widgets",wp_inactive_widgets +``` + +### Export sidebars as JSON + +```bash +$ wp sidebar list --format=json +[ + { + "name": "Widget Area", + "id": "sidebar-1", + "description": "Main sidebar area", + "class": "widget-area" + }, + { + "name": "Inactive Widgets", + "id": "wp_inactive_widgets", + "description": "", + "class": "" + } +] +``` + +### Count total sidebars + +```bash +$ wp sidebar list --format=count +2 +``` + +### Display sidebars with descriptions + +```bash +$ wp sidebar list --fields=name,description ++--------------------+--------------------------------------+ +| name | description | ++--------------------+--------------------------------------+ +| Primary Sidebar | Main sidebar in the page layout | +| Footer Widgets | Footer widget area (4 columns) | +| Inactive Widgets | Area for unused widgets | ++--------------------+--------------------------------------+ +``` + +### List sidebars excluding inactive ones + +```bash +$ wp sidebar list --fields=name,id --exclude-inactive ++------------------+----------+ +| name | id | ++------------------+----------+ +| Primary Sidebar | sidebar-1| +| Footer Widgets | footer-1 | ++------------------+----------+ +``` + +### Search for a specific sidebar + +```bash +$ wp sidebar list --search=Footer --fields=name,id ++-----------------+---------+ +| name | id | ++-----------------+---------+ +| Footer Widgets | footer-1| ++-----------------+---------+ +``` + +### Get sidebar information with HTML markup + +```bash +$ wp sidebar list --fields=name,id,before_widget,after_widget --format=json +[ + { + "name": "Widget Area", + "id": "sidebar-1", + "before_widget": "
", + "after_widget": "
" + } +] +``` + +## Common Use Cases + +### Export sidebar structure for backup or documentation + +```bash +wp sidebar list --format=json > sidebars_backup.json +``` + +### Verify sidebar registration in a theme + +```bash +wp sidebar list --fields=name,id +``` + +### Automate widget area setup scripts + +```bash +wp sidebar list --format=csv | tail -n +2 | while IFS=',' read -r name id; do + echo "Processing sidebar: $name ($id)" +done +``` + +### Integration with other commands + +```bash +# List only active sidebars and count them +wp sidebar list --exclude-inactive --format=count +``` + +## Tips & Best Practices + +1. **Use `--format=json`** for programmatic access and scripting +2. **Combine with `--fields`** to reduce output noise and focus on needed information +3. **Verify sidebars exist** before registering widgets with them in custom scripts +4. **Use `--search`** to quickly locate specific sidebars in theme with many registered areas +5. **Export as CSV** for spreadsheet analysis or documentation purposes + +## Resources + +- [WordPress Sidebars Documentation](https://developer.wordpress.org/themes/functionality/sidebars/) + +## Notes + +- The `wp_inactive_widgets` sidebar is a special WordPress sidebar where widgets can be placed but won't be displayed on the site +- Sidebar IDs must be unique within a WordPress installation +- Sidebars are typically registered in theme `functions.php` files using `register_sidebar()` +- Different themes may have different sidebar configurations \ No newline at end of file