Skip to content

Using the Github wiki

Jump to bottom
Shawn South edited this page Feb 11, 2014 · 2 revisions

The Github wiki parser supports several markup languages. We have chosen to use Markdown because it is the default, is easily portable and Github has enhanced it to integrate with other Github services.

General references

Searching the wiki

Github does not provide a mechanism for directly searching wiki contents. There are two recommended work-arounds: Perform a Google site: search (which does not appear to work), and the Github Wiki Search browser add-on. (@shawn-bellevuecollege has confirmed the add-on on Firefox.)

Additional syntax notes

This section documents oddities and/or syntax not well documented elsewhere. It is assumed that you have already familiarized yourself with the reference material listed above.

Formatting

Nested bold/italics

The parser doesn't seem to handle nesting bold and italic formatting unless the characters are different. For example, this will confuse the parser:

**bold text *with italics***

Instead, use the following syntax:

**bold text _with italics_**

Images

The image syntax for traditional Markdown works:

![alt text](images/someImage.png)

But if you want more control over how the image is placed, the Github wiki now supports a syntax that will allow you to do that:

[[images/someImage.png|frame|align=right|float|alt=alt text]]

You can use any, all or none of the additional attributes to control how the image is displayed. For more information, see the Gollum documentation for image syntax.

Image file locations

Yes, you can store your images in the wiki repository itself, and in sub-folders. There is a difference to be aware of in the two formats listed above, however.

  • In the first example, the images folder is expected to be at the root of the repository.
  • In the second example (of the newer syntax) the images folder is relative to the folder for the currently-displayed wiki page.

This latter behavior can be confusing because from the viewer's standpoint there is no hierarchy to pages. Given the following folder structure in the repository:

  • (root)
    • Page1.md
    • images
    • SubFolder
      • Page2.md

The URLs are:

http://github.com/someRepo/wiki/Page1
http://github.com/someRepo/wiki/Page2

Also, you cannot traverse parent folders to reference an image. The following does not work:

[[../images/someImage.png]]

Anchors

The Github wiki seems particularly picky when linking to headings within a wiki page. An anchor-enabled link looks something like this:

[[Some Page#some heading]]

Anchors must

  1. be in all lower case
  2. have spaces replaced with dashes (-)
  3. have all(?) punctuation stripped out (stripping of periods (.) and ampersands (&) has been observed)
  4. be prefixed with wiki-

The parser will take care of numbers 2-4, but if any of the characters are upper cased, it will link to the page but not be able to find the anchor. (If the wiki- prefix already exists, the parser will not add it.)

After being parsed, the link for the example above would look something like this:

http://github.com/someRepo/wiki/Some-Page#wiki-some-heading

Linking to an anchor on the same page

The normal wiki page-link syntax doesn't seem to work for this. Use the standard link syntax with just the anchor:

[some text](#some-heading)
Clone this wiki locally