Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Codex:Styles

The following are samples of markup used by the editors of WordPress Codex to create examples which present how various template tags and markup might look like when used in a user's template files or WordPress post editor. For information on MediaWiki formatting markup, see the Editing Help article.

Styling Codes in WordPress Codex

By convention, samples of code are formatted with a monospaced (also called non-proportional) font. Displaying a programming code, HMTL and CSS are common within WordPress Codex. The code can be styled in several different ways.

Code within a running text 
To style a code within a body of text, such as when referring to the name of a function or variable, use the <tt> tag to wrap the code within a sentence. The <code> tag also works, but in the past, that created an annoying blue background. In WordPress Codex, stick with <tt> to be safe. If using a URL within the <tt> or <code> tag, use <nowiki> to force the URL not to generate into an active link. Note that, as opposed to the <pre> tag, the MediaWiki markup used within these tags is interpreted, not displayed. See how to make a web browser display the WikiMedia markup.
Block of code 
To style a block of code so it is separate from the surrounding text and highlighted in a grey colored background container, use the <pre> tag to wrap the code. Note that the MediaWiki markup used within the <pre> tag is displayed as is, not interpreted.
<pre> tag shortcut 
If you are writing only a few very short lines of code so they do not wrap to a new line, you can put a space before the code and the software will automatically generate a <pre> tag around the code. Note that, as opposed to the <pre> tag, the MediaWiki markup used within this shortcut is interpreted, not displayed.
<pre> tag limits 
The <pre> tag is great for highlighting a block of code, but it still behaves the same way as any HTML <pre> tag. The white-space characters (tabs, spaces and new lines) within a <pre> tag will be evident. Long lines that exceed the width of the article will be automatically wrapped to a new line. Use your best judgement to force line breaks and then indent the new line in the code, thus shortening the line width manually to increase the readability. Avoid huge indentations to push the code over. Use two or more spaces rather than tabs for long lines of code to provide indentation.
Emulating the <pre> tag 
Using the example below, you can create a <div> container styled with CSS to emulate the <pre> tag appearance, but the code will actually be plain text within the container, made to look like code through the use of <tt>, by changing the > and < characters into the &gt; and &lt; entities, and by use of <br /> to break lines within the code example. The alleged benefit of this style was that the code automatically wraps when a space is used, allowing longer lengths of code to be showcased, but the same is true when using the <pre> tag which is a recommended way of code styling.
<div style="padding: 1em; border: 1px dashed #2f6fab; 
color: Black; background-color: #f9f9f9; line-height: 1.1em">
<tt>
&lt;div class="post" id="post-&lt;?php the_ID(); ?&gt;"&gt;<br />&lt;h2&gt;&lt;a href="&lt;?php the_permalink() ?&gt;" rel="bookmark" title="Permanent Link to &lt;?php the_title_attribute(); ?&gt;"&gt;&lt;?php the_title(); ?&gt;&lt;/a&gt;&lt;/h2&gt;<br /><br />&lt;small&gt;&lt;?php the_time('F jS, Y') ?&gt; &lt;!-- by &lt;?php the_author() ?&gt; --&gt;&lt;/small&gt;
</tt>
</div>

which will generate this <pre>-like block:

<div class="post" id="post-<?php the_ID(); ?>">
<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></h2>

<small><?php the_time('F jS, Y') ?> <!-- by <?php the_author() ?> --></small>


For more information on using character entities, see Fun Character Entities.

Examples

Users of WordPress Codex like to see what the end result will look like before they try the given markup or code. When possible, here are some examples of realistic examples that may be used within the Codex pages.

Realistic Examples

When a realistic example is required to show what the usage would look like in a post, use the following as an example - modifying it as needed to change the padding, width, and colors. In general, you should modify the look of the font and not use font-family references. In order to avoid font issues with various browsers and computer systems, you should rely on the default fonts with the Codex.

This box demonstrates what a code looks like when used in the "real world". I can use spans to style sections and other CSS inline styles to customize the look like for this list:
  • A List Item in Small Caps
  • List Item in Italic and Bold
  • Change Size and Color

There are limits, like you can't recreate a hover, but for the most part, all inline CSS styles can be used on the Codex to recreate a realistic example of what the usage will generate.

and the code is this:

<div style="border:1px solid blue; width:50%; margin: 20px; padding:20px">
This box demonstrates what a code looks like when used in the "real world".  I can use 
<span style="color:red; font-weight:bold">spans to 
style sections</span> and other CSS inline styles 
to customize the look like for this list:
<ul>
<li style="color:green; font-variant:small-caps">A List Item in Small Caps</li>
<li style="color:blue; font-style:italic; font-weight: bold">List Item in Italic and Bold</li>
<li style="color:maroon; font-weight:bold; font-size: 120%">Change Size and Color</li></ul>
There are limits, like you can't recreate a hover, 
but for the most part, all inline CSS styles can be 
used on the Codex to recreate a realistic example of
 what the usage will generate.</div>

Display an URL Without Creating a Link

To NOT automatically create a link for an example URL, like http://example.com/index.php, i.e. bypassing the MediaWIki auto-link feature, wrap the URL with the <nowiki> tags:

<nowiki>http://example.com/index.php</nowiki>

Making a Live Link Example

When creating a live link within an example, link it to the heading in which that example is being used, instead of linking it to a random unrelated URL such as www.example.com. If you are in an article called "Using WordPress" and showing an example under the heading "List Categories", then the example links to the categories would be:

* [[#List_Categories|My Life Stories]]
* [[#List_Categories|My Family]]
* [[#List_Categories|Sharing]]
* [[#List_Categories|Facts and Fiction]]

and the result would look like this, using the realistic examples code from above:

Creating Fake Links

To create the look of a link for a span of text within an example, without having it actually behave like a link, you can use the <span> tag combined with the underline <u> tag or CSS styles, thus making a fake link like:

See <span style="color:blue"><u>this article</u></span> for more information

and the result would look like this, using the realistic examples code from above:

See this article for more information.

Using Images in the Codex

Images related to WordPress and WordPress articles are welcome in the Codex. We do have some "rules" about the images.

  • Do not use spaces in the file names. Dashes are acceptable.
  • Name it what it is, not its usage or description. For example, this-is-a-screen-shot-of-link-manager.png is not clear. Use link-manager-panel.png.
  • Keep image width no larger than 600 pixels, if possible.
  • Keep file sizes small, preferably below 60K when possible.
  • The file types preferred are JPG and PNG. The PNG files tend to be best.
  • If you resize an image to make it much smaller, be sure and sharpen it before saving and uploading.
  • If you have uploaded an image incorrectly, upload a new version and let one of the Documentation team know to delete the old image.

You can use images within the Codex as full-sized or thumbnails.

To use images within the Codex:

[[Image:Kubrick_Single.jpg|right|thumbnail|WordPress Default Theme - Single Post Look]]
WordPress Default Theme - Single Post Look
Will create the image floated to the right in a thumbnail with a caption.

To put an image floated to the right or left that is not a thumbnail:

[[Image:leaf.gif|left]]
leaf.gif
The image of the leaf will float to the left without a link or a border around it. It is simply a graphic used to set an example of floating an image to the left (or right) of text, as exemplified in the article Wrapping Text Around Images.


To put an image floated to the right (or left) with a caption that is not a thumbnail use:

[[Image:leaf.gif|right|frame|Image of a leaf]]
Image of a leaf
This examples puts a frame around a non-thumbnail image so the text will wrap around the image. The image will sit in a bordered container with a caption but with no link signaling a larger version of the image. Though the picture itself is still a link to view it separately, it is not an enlarged version. This is useful for small images that require a caption.

Related

Resources