Migrating Working Group wiki pages - mpi-forum/mpi-issues GitHub Wiki

Trac will be made read-only as of 13 November, 2015. After this date:

  • Working groups will no longer be able to edit their wiki pages
  • It's more annoying/difficult to get the ticket description wiki source (you can click on the "Plain text" link at the bottom of a ticket page)

Working groups will also no longer be able to obtain their wiki source code (!)**

As such, working groups are STRONGLY advised to migrate their wiki pages to Github before 13 November, 2015.

Overview

Working groups are responsible for migrating their own wiki pages. No wiki pages will be migrated automatically. The old Trac wiki pages will not be deleted and can still be linked to for history, but new content must be created on the new GitHub wiki.

Migrating your wiki pages is not difficult. The general workflow is:

  1. Open a Trac wiki page
  2. Click "Edit this page" (just like you would have edited the page before)
  3. Select all the text and copy it
  4. Open a new, corresponding wiki page in your working group's Github organization (list of pages here)
  5. Paste the content in
  6. Make any minor changes to accommodate the different wiki styles
  7. Save the Github wiki page

Here are two useful links for Github Markdown documentation (the wiki syntax that Github uses):

Fun (and useful) fact

Note that Github wikis are actually Git repositories -- you can clone the wiki to your favorite text-editing platform, make all your changes, commit them to the git repository, and then push them back up to Github. The edits will (more or less) immediately be live on the wiki.

The URL for the wiki is shown on the right hand side of all wiki pages (assuming you have write privileges to the wiki).

The individual files in the wiki Git repository will have a .md file extension. The front page must be named Home.md (not index.md).

Github wiki editor

The Github wiki editor has three useful features:

  • Several buttons for common wiki actions (boldface, italics, links, ...etc.)
  • A "?" button for providing inline help in Github's "Markdown" wiki syntax
  • A "Preview" tab to let you see how what you have typed will render

Typical Trac / Github Markdown wiki differences

Here's a list of some wiki differences that you'll likely need to update when you bring Trac pages over to Github:

  • Links are marked differently:

    • Trac: [URL text for the link]
    • Github: [text for the link](URL)
    • Both will auto-link naked URLs

  • Headers are different:

    • Trac: = Title = (use more equals for smaller sections)
    • Github: # Title (use more hashes for smaller sections)

  • Images are different:

    • Trac: [image(URL)](/mpi-forum/mpi-issues/wiki/image(URL))
    • Github: ![Alt text](URL of image)
    • Note that you can add images directly to the wiki repository, and then link to them

  • Tables are different

  • Bullets and enumerated lists are (essentially) the same (yay!)

    • Both: * Bullet item
    • Both: 1. Enumerated item
    • You might still want to ensure that they render the same (or well enough)

  • Verbatim text is different:

    • Trac: {{{ blah }}}

    • Github:

      • Inline verbatim: put text in single quotes, like this
      • Multi-line verbatim: have a line with 3 single quotes, then your verbatim text, then another line of 3 single quotes.
      • Multi-line verbatim can also accept a token to indicate a particular flavor of syntax highlighting to use inside the block. For example:
      ```c
int foo(void) { printf("Hello, world\n"); }
    ```

      The above renders as:

      int foo(void) { printf("Hello, world\n"); }