Skip to content

Wiki quick start

Steve Harris (drstevok-test1) edited this page Jan 2, 2016 · 3 revisions

Notes on creating pages for the wiki.

You will, of course, need a github account for this (join here)

Quick walkthough

There are two methods: creating and editing the page online (the easiest), and creating and editing the page offline. A compromise is to write the page offline in a text editor (e.g. notepad or similar on Windows, or TextEdit on a Mac), and then copy-paste the text into the online editor.

Online

  1. Go to https://github.com/datascibc/datasci4docs/wiki (this wiki)
  2. Click the green New Page button
  3. Enter your page title
  4. Write your content
  5. Enter a brief note in the Edit Message box. If this is a new page then 'Created new page on my favourite topic', or if this an edit to an existing page then simply note what you did.
  6. Click the green Save Page button, and you're done!

On your own computer

  1. Copy the wiki to your own computer (called cloning in git parlance)

    • if your comfortable at the command line then just type git clone https://github.com/datascibc/datasci4docs.wiki.git at the command line (after navigating to an appropriate folder)
    • otherwise just install the Github Desktop app (available for Mac and Windows); log in to your account; then go back to your browser and the wiki page and click the Clone in Desktop button
  2. Create a new file in the folder (directory) datasci4docs.wiki using a text editor --- both Notepad (Windows) and or TextEdit (Mac OSX) are free apps included with the operating system, or download Atom (also free, and from GitHub).

    • name the file in a memorable way as this will also become the text that you use if you wish to link your page elsewhere in the wiki.1
    • use the .md (for markdown) as the file extension

    For example,

    • the course programme page would be saved in a file called course-programme.md
    • an 'FAQ' page would saved in a file called faq.md
  3. Enter your content using markdown syntax

  4. Save your file using the text editor as usual, but now switch back to the GitHub Desktop app, and commit (aka save) and push (aka sync) your changes with the version of the wiki on the website.

Basic syntax

There are just two bits of 'plain text' writing to master in order to create your wiki page: markdown and the gollum2 wiki syntax. Both of just ways of writing beautiful and useful documents in a very simple, readable style, but without the need for any fancy applications.

Markdown

Markdown is just a systematic method for assigning meaning to parts of your document. In Microsoft Word or similar, we are used to bolding text using a menu or keyboard shortcut. In Markdown, just type two stars before and after the words to be emphasised (**two stars** becomes two stars). All possible options you might need are detailed at the GitHub Markdown guide.

Just click on the edit button on this wiki to see this page in its original markdown format.

Gollum wiki

We are all familiar with wikipedia which differs from an old fashioned reference in that any term on one page can be linked to another page. To make a link, simply take the filename and enclose it in double square brackets [[my test page]].

There's a teeny bit of magic here. The wiki takes any text inside the double square brackets, swaps spaces for hyphens, and then looks for a file named in the same way. [[my test page]] becomes my-test-page and will link to a file called my-test-page.md. Note the addition of the markdown (.md) extension.

You can do perform the work yourself, but then you need to use the standard markdown link syntax which puts the link text inside square brackets (i.e. [click here]) and then the filename follows in parentheses (my-test-page.md). Together this would be typed as [click here](my-test-page.md) and appear to the reader as click here.


1: File names can only contain alpha-numeric charactacters and hyphens. No other punctuation is permitted so beware apostophes and periods etc. Filenames are not case sensitive.

2: Their name not mine!