Codex

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

User:Cn-cuckoo/样式规范

This article is a ROUGH DRAFT. The author is still working on this document, so please do not edit this without the author's permission. The content within this article may not yet be verified or valid. This information is subject to change.
原文链接:Codex:Styles

The following are samples of code used within the WordPress Codex for presenting examples of tag and code use. They involve familiarity with HTML and CSS, as well as MediaWiki markup.

Overall Styles

Layouts of articles within WordPress Codex follow a simple convention. Articles normally start with a descriptive paragraph, though sometimes it may start with a title followed by an introductory paragraph. Following that, then the rest of the article is presented, and is divided into concise sections of information, examples, and images that help WordPress users understand the concept under discussion.

Resources are usually found at the end of the article in the section title Resources and may include links to external sites. External links should be limited to the most reliable and consistent sources, preferably non-commercial sites, when possible.

Section titles are styled through the MediaWiki markup style using equal signs. The first section title should be marked with two equal signs (==) on both sides. Spaces or lack of spaces between the words and the equal signs will not affect the end result.

Second level section titles should be marked with three equal signs (===), and the third level with four (====), and the fourth with five (=====). Rarely do articles have more than four subsections.

A good example of an article which uses all of the layout styles within WordPress Codex is Styling Lists with CSS. A good example of the non-code writing style is found at WordPress Semantics.

Table of Contents

The table of contents featured on every page is generated automatically when four sections have been created. It sets itself to float to the right side of the content of the first section title. To force a table of contents onto a page in a particular place, or on an article that lacks more than four sections, you can use __TOC__ to place or force the table of contents.

Using Codes in the Codex

Displaying programming codes, HMTL, and CSS is common within the WordPress Codex. It can be styled in several different ways.

Code within the text 
To style code within the text of an article, such as listing the index.php template file, use the <tt> tag to wrap the code within a sentence. <code> tags also work, but in the past they used an annoying blue background. Stick with <tt> to be safe.
Code in a PRE tag 
To style code so it is separate from the text and highlighted in a blue colored background container, use <pre> tags to surround the code. Do not use <tt> or <code> within the PRE tags unless you want to show those tags. If using a link within a PRE tag, use <nowiki> to force the link to not generate into an active link.
PRE Shortcut 
If you are writing a very short line of code, you can put a space before the code and the software will automatically generate a <pre> tag around the code.
PRE Limits 
The <pre> tag is great for highlighting text, but it still functions the same as any HTML <pre> tag. The layout of the code within a <pre>, with tabs, spaces, and long lines, will all be evident. Long lines that exceed the width of the page will run off the page. When possible, force line breaks in the code to shorten the width manually. When not possible (it will break the code if copied and pasted exactly as written), then use your best judgment. Avoid huge indentions and tabs to push the code over. Use two or more spaces rather than tabs for long lines of code to provide indention.
Wrapping Code 
Using the example below, you can create a div styled with CSS to emulate the <pre> tag usage, but the code will be actually text within a container, made to look like code through the use of <tt> and changing > and < into &gt; and &lt; and line breaks <br /> within the code example. The benefit of this style is that the code will automatically wrap when a space is used, allowing longer lengths of code to be showcased.
<div class="post" id="post-<?php the_ID(); ?>"><

<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2>

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

In which the code looks like this:

<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;&lt;br /&gt;
&lt;h2&gt;&lt;a href="&lt;?php the_permalink() ?&gt;" rel="bookmark" title="Permanent Link to &lt;?php the_title(); ?&gt;"&gt;&lt;?php the_title(); ?&gt;&lt;/a&gt;&lt;/h2&gt;&lt;br /&gt;
&lt;small&gt;&lt;?php the_time('F jS, Y') ?&gt; &lt;!-- by &lt;?php the_author() ?&gt; --&gt;&lt;/small&gt;
</tt>
</div>

For more information on using character entities or codes within a document, see Writing Code in Your Posts.

Examples

Users of the Codex like to "see" what the end result will look like before they try it. When possible, here are some examples of "realistic" examples that may be used within the Codex.

Realistic Examples

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

Box in which to provide demonstration of 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">
Box in which to provide demonstration of 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>

Showing Links Without Links

To NOT show a link in an example like http://example.com/index.php which uses a link use <nowiki>:

<a title="example" href="<nowiki>http://example.com/</nowiki>">

Making a Live Link Example

To create an example link, link to the heading in which that example is being used. 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 results would look like this, using the demonstration code from above:

Showing Links that Work Like Links

To create the look of an example link, without having it actually behave like a link, you can use the span tag combined with underline to style a fake link:

See <span style="color:blue"><u>this article</u></span> for more information
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 files 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]]
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.

Resources