Contributor Handbooks

Contributor handbooks are located on make.wordpress.org/[team-name]/handbook/. Each team can opt-in to having a handbook.

Setup Setup

To setup a contributor handbook, a network admin needs to do the following:

  1. Enable the Handbook plugin.
  2. Create a new Handbook page called “Handbook” with the slug of “handbook.”
  3. Go into Settings -> Permalinks and press the “Save Changes” button.

The handbook is now (mostly) setup and new pages will be visible to users.

Top ↑

The handbook sidebar (menu) is auto-generated based on the “Order” and “Parent” attributes of each handbook page. New published pages appear automatically in the sidebar.

In the past, the handbook sidebar was a custom menu and some sites still opt-in to this method, though it is not recommended. In this world, new pages in handbooks would not automatically show. Initially, a new menu needs to be created. Creating the menu required the following:

  1. Go to Appearance -> Menus and “create a new menu” called “Table of Contents” (or anything, really).
  2. Add any Handbook page to the menu and save the menu.
  3. Go to Appearance -> Widgets. In the Handbook widget area, add a Custom Menu and select the the “Table of Contents” menu.
  4. Name this menu whatever you’d like to show in the header above the sidebar. Often, teams choose “Chapters.”

Top ↑

Shortcodes Shortcodes

When enabled, the handbook plugin offers a few shortcodes that can be used throughout the site. These shortcodes (described below) can be used anywhere on the site and are not limited to the handbook CPT. All of these shortcodes require closing tags.

Note: The [ info ] shortcode is used to display informational messages.

Tip: Use the [ tip ] shortcode to highlight tips.

Alert: The [ alert ] shortcode is for alerting readers to important messages.

Warning: When something is particularly precarious, use the [ warning ] shortcode.

Tutorial: Tutorial lessons should use the [ tutorial ] shortcode, but should continue on from previous tutorials.

Top ↑

Naming Naming

In some cases, your site might not want to use the standard handbook name. Currently, we use the meta team’s name for the handbook name. For example, the “core” team’s handbook is called the “Core Handbook.” However, this doesn’t make as much sense for the polyglots team. The handbook name is changeable using the following steps:

  • Go to Settings –> General for the site you want to change.
  • Find the option for “Handbook name” on that page and change it.
  • Save Changes.

Easy, right? Yay!