Adding Code Blocks to a Wiki Page

From PikaDocs

By Brian Lawlor & Mark Sawyer
Legal Services of Northern California (http://www.lsnc.net/)

Table of contents

1 Creating and editing code blocks 2 Adding highlighting to code blocks

Creating and editing code blocks

PikaDocs is built on the MediaWiki (http://wikipedia.sourceforge.net/) platform, which includes a set of distinctive skins (http://meta.wikimedia.org/wiki/Skins) with corresponding user styles (http://meta.wikimedia.org/wiki/User_style) or cascading style sheets (CSS) to provide a defined look to the site. The most obvious examples of these style elements are common web page presentational characteristics like the particular font, font color, font size, background color, and so on.

Less obvious but very useful are other presentational characteristics that you may have seen used on various pages at PikaDocs. One of the most useful is the pre (http://www.htmldog.com/reference/htmltags/pre/) tag (preformatted text) used to display code. It is particularly useful because it maintains the line indentations and line breaks created in the original code text. For example, the XHTML structural markup code displayed at the Project Claire: default.html page illustrates how the code appears when the pre tag is applied to enclose the code. By default, the code block enclosed by a pre tag is displayed using a a one-pixel, dark-blue, dashed border, the background color changes, there is some padding to separate the text from the border, the font changes to Courier New and, importantly, the indentations of code lines are preserved. Handy dandy, no?

Here's a simple example: Let's say your PikaDocs article includes an example of a small, four-cell table with a yellow background and a blue, dashed border that looks like this:

cell 01	cell 02
cell 03	cell 04

To include the table "code" or markup itself, rather than the "presentation" of the table as it appears in the web page, in the edit page enclose the table markup (including its line indentations and line breaks as you want them to appear) with pre tags, like this:

<pre>
<table style="background-color: yellow; border: 2px dashed blue;">
<tr>
    <td>cell 01</td>
    <td>cell 02</td>
</tr>
<tr>
    <td>cell 03</td>
    <td>cell 04</td>
</tr>
</table>
</pre>

Save your edit and the pre tags do their magic, displaying your code block with line indentations and line breaks intact:

<table style="background-color: yellow; border: 2px dashed blue;">
<tr>
    <td>cell 01</td>
    <td>cell 02</td>
</tr>
<tr>
    <td>cell 03</td>
    <td>cell 04</td>
</tr>
</table>

Adding highlighting to code blocks

Okay, that's dandy as far as it goes. But let's say you've done the editing above to create a nicely formatted code block, but you also want to add some yellow highlighting to a particular part of the code. You'll quickly discover you cannot just add a span (http://www.htmldog.com/reference/htmltags/span/) tag with a style attribute (e.g., <span style="background-color: yellow;"> to get that effect. It won't work using the pre tag.

To pull this trick off, you need to use a different set of tags that permit use of the span tag while mimicking the look you get with pre tags. To illustrate how to do this, we'll use the following three-line code block from the top of the Project Claire: default.html template:

<title>Pika: %%[page_title]%%</title>
<link rel="stylesheet" type="text/css" href="%%[base_url]%%/css/danio.css" />
</head>

To mimic the PikaDocs pre style, we use a combination of div (http://www.htmldog.com/reference/htmltags/div/) (division), tt (http://www.htmldog.com/reference/htmltags/presentational/) (teletype) and br (http://www.htmldog.com/reference/htmltags/br/) (line break) tags:

• First, add br tags at the end of each line (except the last line) to preserve the line breaks in the original code:

<title>Pika: %%[page_title]%%</title><br />
<link rel="stylesheet" type="text/css" href="%%[base_url]%%/css/danio.css" /><br />
</head>

• Second, add a span tag with a style attribute applying a yellow background to the text %%[page title]%%, as illustrated here:

<title>Pika: <span style="background-color: yellow;">%%[page_title]%%</span></title><br />
<link rel="stylesheet" type="text/css" href="%%[base_url]%%/css/danio.css" /><br />
</head>

• Third, enclose the entire code block in div and tt tags. The div tag includes style attributes to create the same border, margins and background color used for the pre tag, described above; and adding the tt tag is a quick and dirty way to substitute the Courier New font-family, again mimicking the pre default style:

<div style="padding: 6px 12px; margin: 20px 0; background-color:#F9F9F9; border: 1px dashed #2F6FAB;">
<tt>
<title>Pika: <span style="background-color: yellow;">%%[page_title]%%</span></title><br />
<link rel="stylesheet" type="text/css" href="%%[base_url]%%/css/danio.css" /><br />
</head>
</tt>
</div>

Pop this edited code block into your PikaDocs editing screen, save it, and you get your nicely formatted code block with highlighting in yellow of whatever particular snippet you enclose with the span tag: