Advanced Editing Assistance

This page provides a summary of “advanced” editing information. Most of these details will only be of interest to editors that need to make structural changes (add pages/namespaces, work with menus, etc.) or make more advanced formatting edits. Editors that only need to make simple edits to existing pages should start with the Basic Editing Assistance notes.

As this wiki uses the Dokuwiki framework, complete usage and editing details can be referenced in the full Dokuwiki manual. This page summarizes some of the details found there, or details unique to this wiki setup, for quick reference.

Before editing or changing any wiki structures, you need to know how wiki pages are organized. Dokuwiki structures all pages in a tree of “namespaces”. Basically, you may picture namespaces as directories, and pages as files inside them. Any page's complete internal “pagename” includes the namespaces it is within, (much like a hierarchical path), separated by colons.

Therefore the a:b:c pagename can be pictured as:

   root namespace (always present)
     |
     +-- 'a' namespace
           |
           +-- 'b' namespace
                 |
                 +-- 'c' pagename

Note that you can have a pagename and a namespace with the same name, at the same time, within any namespace. Back to the above example, the a:b pagename can be pictured as:

   root namespace (always present)
     |
     +-- 'a' namespace
           |
           +-- 'b' pagename (not to be confused with the 'b' namespace above)

Note that:

• Namespaces only “exist” to contain and organize pages. Unlike a folder on a computer, you can't have an empty namespace. In other words, a namespace is only “born” once a page is defined “within” it (as part of the page's pagename, ie. namespace:page).
• For reference, each page's internal pagename appears at the bottom of each page (in the footer) surrounded by brackets. This provides easy cut-and-paste reference for defining links to the page.

For clarity and consistency, it is good practice to define a “start” page for each namespace using a consistent naming scheme. This is a regular page that serves as an “index”, or “base” page for the namespace (for editors that know html, you could think of this as analogous to a index.html page in a static website). For this we reserve the name “start”. So pagename a:b:start would be a “start” index page for the b namespace. These start pages are also treated specially (as base/index links for the namespace) in any automatic/dynamic menus, such as the “you are here” links.

Generally, when your browser requests a pagename that doesn't already exist, DokuWiki will (depending on your access rights) present you with the option to create it. For example, you can:

• Direct your browser to the URL of the desired new pagename (note: within URLs, namespaces are separated with slashes instead of colons). For example, you could browse to any existing page in a existing namespace (generally relative to the location you want to add a page), and then edit the URL text (in your browser) to reflect the pagename you want to create, and hit enter.
• Enter a new pagename (including the page's namespace(s) separated by colons) in the search box and click “go”
• Create a link to the new pagename (including the page's namespace(s) separated by colons) on another DokuWiki page and follow it with your browser.

If the pagename path contains namespaces that don't already exist, they will also be created (but their “start” pages will not exist until created individually).

It is important to understand the distinction between “pagenames” and “page titles”.

• Pagenames, described above, are static internal “paths” for each page, they are also used to define the page's URL. When working with a page's wikicode (defining a link to another wiki page, etc) you will usually be working with pagenames.
• Page Titles, on the other hand, are dynamic text titles for each page. These titles are automatically used when listing a page in a dynamic menu (such as the “you are here” links), or when displaying an internal link to that page. Page titles can only be defined after the pagename (and thus the page itself) is created.

This wiki is configured to automatically use each page's first heading as the “page title”. As a result, it is good practice to start each page with a level 1 heading (H1) that defines this page title. If you later need to change it, simply adjusting the text in this first heading will change the text that appears for that page's links throughout the wiki, in one step. Note however, that you will always use the same “static” pagename to define links in wikicode, regardless of the page title.

Some notes about how menus and navigation structures can be inserted into the wiki

When any individual page contains more than 3 headings, a small “table of contents” menu is automatically generated in the upper-right corner of the page. These links allow readers to “jump” to any heading in a long page.

If you do not want this table of contents to automatically appear, you can insert a line like:

~~NOTOC~~

anywhere on the page.

In order to insert navigation menus for full namespaces and pages, we use the Indexmenu plugin. It allows us to insert an automatic/dynamic menu of pages into any wiki page, with a small line of wikicode.

The full details and syntax for defining a menu are best referenced at the official indexmenu plugin page. However, for common reference, the wikicode to insert a menu of the current namespace into a page (as a set of bullets, showing the namespace tree 1-level deep, and correctly sorted) is:

{{indexmenu>.#1|msort nsort}}

And to do the same, but in the style of a fancy folding javascript tree:

{{indexmenu>.#1|js msort nsort}}

Some important notes about the way these menus are sorted (this may only impact documentation trees that must be ordered a certain way):

• By default namespaces and pages are sorted alphabetically
• If alphabetical ordering is inappropriate, pages within a namespace can be ordered in a custom way by adding a line like:

  {{indexmenu_n>2}}

  into each page (within a given namespace). This essentially “numbers” each page (in this example we are setting page 2) so that when inserting a menu using the “msort” option (such as the examples above), pages will be ordered by these “page numbers” in the menu tree.

• Each individual level of namespaces can be sorted the same way as pages, by also adding a line like {{indexmenu_n>2}} (using the appropriate number) into the start page for each namespace on any given level in the tree. This essentially numbers each namespace the same way pages can be numbered. Note that for this to work, the “nsort” option must be used when inserting a menu (such as in the examples above).

All the built-in Dokuwiki syntax possibilities are described on the Formatting Syntax page. However, there are some syntax details that are specific to special formatting plugins that are not listed there. Some notes are included below:

Dynamic colored boxes can be inserted on any wiki pages uses the “box” plugin, such as the example to the right. Boxes can be:

• Floated to the left or right, or simply added inline.
• Given any width
• Displayed using a number of colors definitions (such as “red”, “blue”, “plain”, etc.)
• Given rounded or square corners that are cross-browser friendly.

The example box to the right was created with the following wikicode:

<box right blue round 200px>
This is a box, it was inserted using some basic wikicode.
</box>

For a full explanation of the wikicode used to create boxes, see the officialboxes plugin page.

A similar, but slightly simpler alternative to the “boxes” plugin formatting described above, is the “notes” plugin formatting. Notes can only be inserted inline (no floating) and have fewer customizable options, and thus use a slightly simpler wikicode. Here are some examples:

The last example, the “warning” note, was created with the following wikicode:

<note warning>
An example of a "warning" note.
</note>

For a full explanation of the wikicode used to create notes, see the officialnotes plugin page.

Media (images, documents and other files) can be uploaded into the wiki and displayed and/or linked-within wiki pages. This can included images uploaded and stored within the wiki itself, or from other locations on the internet.

Registered users with the right permissions are allowed to upload various forms of media (images, files, etc.) into the wiki (so that it can later be displayed or linked in a wiki page). These files can be stored and organized within the namespace “tree” hierarchy the same way pages are. This is all managed via a handy tool called the “mediamanager”.

To upload a file, click the “upload file” link in the toolbox (the bottom of the left sidebar). This will open the mediamanager and give you options to upload and browse files stored within that namespace. Note that you may only have upload rights to specific namespaces, and can browse between namespaces using the “tree” menu at the left.

Also note that uploading a file does not automatically display it on any wiki pages, it just makes it available within the wiki for later insertion as needed.

Media is inserted into a page by surrounding the media file's wiki path with curly brakets, like the following “image.jpg” example (uploaded into the advocacy:wiki namespace):

{{advocacy:wiki:image.jpg}}

This will then display the file's contents (if the browsers knows how to display it, ie. an image), or provide a link a reader can use to download the file (if the browser does not know how to display it, ie. a word document).

Fortunately, the wiki edit toolbar provides a shortcut for inserting media (that's already uploaded in the wiki) within a page. When editing, simply place your cursor where the image or media link should be added, or highlight existing text that should be converted into a link, and click the “add images” button in the toolbar. This will open the mediamanger and allow you to browse to the file you want to insert (if it's in a different namespace then your current page location, you need to browse to that namespace with the namespace tree at the left). Then simply click on the filename, and the wikicode will be created in the page you are editing. Of course, you'll need to preview or save the page to see the final result.

Other notes:

• General media from other network/internet locations (not uploaded into the wiki) can also be added to a page, using a form similar to:

  {{http://www.somedomain.com/image.jpg}}

• Images can be resized and displayed in a variety of ways by tweaking the wikicode. See full Formatting Syntax notes for details.
• Detailed help on using the mediamanager is available in the Dokuwiki Manual.

The site template the we are using has a number of blocks, or regions, that can be edited. These regions are not linked directly to a single page of content and thus appear across many pages, and sometimes the whole site.

Some blocks are designed to appear on every page across the entire site (such as the left sidebar and the footer). The content of these blocks is actually just wikicode that can be edited as needed. If you have sufficient permissions, you will see a small “edit” link below these blocks, clicking this will take you into normal wiki page edit mode, and you can make your edits.

This wiki has also been customized to allow a right-hand sidebar to be assigned to any namespace (to appear on all pages in any namespace). To create this sidebar simply create a page called sidebar within any namespace. The contents of this page will automatically be inserted into a narrow block on the top right of all pages in that namespace. Note that:

• Adding a sidebar page to a namespace does not recursively apply it to any sub-namespaces.
• The content of yous sidebar page will automatically be sized to a 200 pixel width, so you do not need to manually set any width properties for you content (but be careful that you don't insert any images or content that will not display well when placed inside a 200 pixel-wide space).
• If using box formatting for your sidebar content (with <box> tags), be sure to specify a 100% width. This will ensure that the box fills the entire space allocated for the sidebar content. For example

  <box blue round 100%>
  ...box content...
  </box>