Placeholders

Placeholders in code and commands represent values that the user must input or replace. Placeholders in outputs can also represent values that differ. Generally, placeholders have a descriptive name and a value.

For example, POST_ID represents a post ID in a code example, command, and example output. In example output, VERSION represents the version of a plugin, theme, or software; the reader is not expected to set this to a specific value.

This page explains how to format placeholder variables in commands and code examples. For more information about other code-related documentation, see Code in text, Code examples, and Command-line syntax.

Placeholder variables

Placeholder variables in inline text

When placeholder variables appear in a sentence, use the following formatting:

• In HTML, enclose inline placeholders in <code><var> elements.

html
<code>PLACEHOLDER_VARIABLE</code>

• In Markdown, enclose inline placeholders in backticks (`) and use an asterisk (*) before the first and second backtick.

markdown
*`PLACEHOLDER_VARIABLE`*

Placeholder variables in code blocks

When placeholder variables are in a block of code, use the following formatting:

{% codetabs %}
{% HTML %}

Enclose the code block in a <pre> element and tag placeholders with <var> elements.

<pre class="prototype">
<img
  src="<var>IMAGE_PATH</var>"
  alt="<var>ALT_TEXT</var>"
/>
</pre>

{% Markdown %}

Enclose the code block in a code fence. You cannot apply text formatting or highlighting such as bold or italic inside a code fence.

“`
*PLACEHOLDER_VARIABLE*
“`

{% end %}

Placeholder variable text

For text in placeholder variables, use uppercase characters with underscore delimiters. If using uppercase characters with underscore delimiters, or capitalizing lowercase characters with already uppercase characters seems inconsistent, then it is acceptable to use another convention; but be consistent with that convention.

Examples

{% codetabs %}
{% HTML %}

Don’t use possessive pronouns in placeholder variables.

Examples
{% codetabs %}
{% HTML %}

{% Markdown %}

For more information about placeholder text in commands, see Optional arguments, Mutually exclusive arguments, and Multiple value arguments.

Describing placeholders

When you use a placeholder in code examples, commands, or other text, include an explanation for what the placeholder represents. Write an explanation for the first time you use the placeholder; if there are multiple placeholders or steps after the first use of that placeholder, you can explain the placeholder again.

Use the following order to describe placeholders:
– Describe what the user is doing.
– Write the code example, command, or other text.
– Explain the placeholder.
– Explain the code example, command, or other text in more detail if required.
– Show any output if required.
– Explain any output if required.

Example

<br />
&lt;pre class=&quot;prototype&quot;&gt;<br />
&lt;img<br />
  src=&quot;&lt;var&gt;IMAGE_PATH&lt;/var&gt;&quot;<br />
  alt=&quot;The WordPress mascot Wapuu.&quot;<br />
/&gt;<br />
&lt;/pre&gt;</p>
<p>&lt;p&gt;Replace the following:&lt;/p&gt;</p>
<p>&lt;ul&gt;<br />
  &lt;li&gt;&lt;code&gt;<var>IMAGE_PATH</var>&lt;/code&gt;: the directory path of the image asset.&lt;/li&gt;<br />
&lt;/ul&gt;<br />

Single placeholder

When writing a single placeholder, replace PLACEHOLDER with a description of what the placeholder represents.

Example

$ wp post delete POST_ID

Multiple placeholders

When there are two or more placeholders in code examples, commands, or other text, use the following formatting:
– Write a descriptive list of all the placeholder variables used in the respective code example, command, or other text, after the code content.
– Explain what each placeholder variable represents.
– Introduce the placeholder description list with Replace the following:
– List all the placeholder variables in the order in which they appear in the code example, command, or other text.
– Provide a description for each placeholder variable.
– Tag each placeholder with <code><var> elements, followed by a colon and lowercase letter as follows:
html
<li><code>PLACEHOLDER</code>: description</li>

Example

$ wp post edit POST_ID --path=PATH --skip-themes[=THEMES]

Placeholders in output

When you specify placeholders in output examples, use the following formatting:
– Write a descriptive list of all the placeholder variables used in the output, after the output example.
– Introduce the placeholder description list with In this output:
– List all the placeholder variables in the order in which they appear in the output example.
– Provide a description for each placeholder variable.
– Tag each placeholder with <code><var> elements, followed by a colon and lowercase letter as follows:
html
<li><code>PLACEHOLDER</code>: description</li>

For more information, see Command output.

Example

{
    "name": "SITE_NAME",
    "description": "SITE_DESCRIPTION",
    "routes": { ... },
    "authentication": {
        "oauth1": {
            "request": "OAUTH_REQUEST_URL",
            "authorize": "OAUTH_AUTHORIZE_URL",
            "access": "http://example.com/oauth/access",
            "version": "0.1"
        }
    }
}