Advertisement

Create a Simple Markdown-Powered Wiki with Torchpad

by

This Cyber Monday Tuts+ courses will be reduced to just $3 (usually $15). Don't miss out.

Wikis are great ways to collaborate on information, whether it’s for your internal documentation or a public website or directory like Wikipedia. The only problem is that wikis are often complicated to create and use, as was easily apparent in our tutorial on building your own wiki. They use an unusual markup language inside an often dated UI. It’s far from surprising that it’s hard to get people to contribute to wikis.

So many content management systems today work with Markdown, the simple text markup language that’s easily converted to HTML. It’s a far simpler way to write formatted text. Torchpad took the simplicity of Markdown and combined it with the power of a wiki to make a far simpler wiki engine.

In this tutorial, you’ll learn everything you need to make your own Markdown-powered wiki in Torchpad and get your team collaborating with a wiki that’s simple to use.

Create Pages

Once you’ve signed up for a Torchpad account, a new wiki will automatically be created for you with a name based on your email address. You’ll then see the Home page for your wiki.

Torchpad default homepage
Torchpad sets you up with an example homepage.

Add a new page to your wiki by clicking the New Page button in the top left of the screen. In the sheet that appears, type the name of your new page in the Page name field. For now, leave the Dir path field blank, and click Create.

Creating a new page
Type a name for your new page.

The new page you just created will be blank, save for the title you gave it. Click the Edit button in the top right to get started adding some content to it, and you’ll see the edit view for that page.

Torchpads editing screen
The edit view contains all the tools you'll need.

In the edit view, you can use any normal Markdown syntax, along with the additions from GitHub-Flavoured Markdown. The buttons along the top can be used to quickly insert the necessary symbols for things like headers, lists and emphasis.

There are a few keyboard shortcuts you can use, which are displayed in the buttons they correspond to. Save your changes with Command-S, and exit the edit view with Command-B. Press Command-D to preview what the page will look like in its current state, which is useful for checking if the Markdown will be interpreted in the way you intended. If you’re not in the edit view, press Command-E to enter it.

Create Pages in Folders

You can also add pages inside folders, if you want to group pages together or give pages URLs with multiple parts. To do this, when you click New Page, add the path you want for the page in the Dir path field. For example, if you want the Cheese page to be located at /Food/Dairy/Cheese, type “Cheese” in the Page name field, and “Food/Dairy” in the Dir path field.

Creating a new page in a folder
Folders can be nested as deep as you like.

Click Create to create the new page, and you’ll see the new page listed in the folder structure you specified.

Add Links Between Pages

When editing a page on Torchpad, there are a couple of extra things you can do that aren’t in standard Markdown. Most importantly, there’s a special syntax for creating an internal link (a link to another page on the same wiki).

To link to another page, surround the name of the page in two sets of square brackets like this: [[Page Name]]. This will automatically create the link for you, instead of having to find the whole URL to put into a Markdown link.

If you’d like to link to a page, but display different text as the link, you can do that too. Just put the text you’d like to display first, followed by a pipe character and then the name of the page, like this: [[Text to display | Page Name]].

Syntax for an internal link
No need to find long URLs to link to pages.

When you visit the page, you’ll see the link displays the text before the pipe, but links to the page named after the pipe.

Internal link on the live page
Links don't have to display the name of the page they link to.

Add Images to Pages

Images can be added to any page just like with regular Markdown, but Torchpad will also host the images for you if they’re not already online with a URL to specify. Drag and drop the image onto the page, and it’ll be uploaded to Torchpad.

Drag and drop an image
Images can be dropped anywhere on a page.

Once it’s uploaded, the Markdown for displaying the image will be inserted automatically. The alt text will be set to the filename of the image you dragged in.

Generated markdown syntax
Torchpad does all the work when inserting an image.

Add Code and Math to Pages

To add a code listing to a page, simply type three backticks on the lines immediately before and after the code.

Syntax for code blocks
Embed some code in your page.

On the live page, the code will be changed to an appropriate font, and syntax highlighting will be applied to make it easier to read.

Rendered code block
Code is much easier to read in a separate styled block.

To change the syntax highlighting to match the language the code is written in, type the name of the language directly after the first set of back ticks, such as ```ruby. This will ensure the code is highlighted properly, picking up the keywords from that language.

As well as code, you can add mathematical formulae to your pages using MathJax. Torchpad treats MathJax as a code language, so surround your MathJax code with triple backticks, and specify the language as mathjax.

MathJax code syntax
Use the MathJax syntax to embed mathematical formulae.

The MathJax code will be rendered on the live wiki page as you’d expect.

Rendered MathJax formula
Rendered formulae are much nicer than plain text.

You can also put MathJax inline, same as code can be inline in a sentence. To do this, surround the code with dollar signs, and surround that with single backticks.

Inline MathJax code
Inline MathJax is just like inline code, with extra $ symbols.

Same as before, the MathJax will be rendered on the live page, but styled to fit inline.

Rendered MathJax inline
Inline MathJax is useful for short, one-line formulae.

Publish Edited Pages

Once you’ve finished editing a page, you’ll want to show it to the world. To publish a page, finish editing and exit the edit view. Click on Draft next to the Edit button, and choose eitherPublish or Set Private.

Publish menu
Individual pages can be public or private.

Choosing Publish makes the page accessible by anyone without being logged into Torchpad. Choose Set Private to make the page only accessible to people who are authors on your wiki. If someone who isn’t part of your wiki tries to access a private page, they’ll see a “not found” message, as if the page didn’t exist at all.

Wiki Settings

There are a few settings you can change for a Torchpad wiki. Click Settings on the left, above the page list, to access them.

Torchpad settings screen
There aren't many settings, but what else could you need?

The Subdomain option lets you change the URL for your wiki. You can choose anything you want here, and your wiki’s URL will become http://what-you-chose.torchpad.com.

The Wiki name option changes the name of the entire wiki. The name you choose is displayed in the title bar of your wiki, and doesn’t have to match the subdomain you pick.

Check the Private Wiki checkbox to make the entire wiki private. This means that only members of your wiki can view it.

Finally, grab your Google Analytics ID from the Analytics site, and paste it into the Google Analytics ID field. This will log any visits to your wiki to Google Analytics to allow you to monitor traffic to it.

Add Members

The important part of a wiki is collaboration, which means you need to add some more people. To get started, click Settings, and then navigate to the Members page.

Members page
Wikis are designed for collaboration, so add some more authors.

Add a new member by typing their email address into the Email field. Then, choose a Role. An owner has full administrative privileges, meaning they can change anything you can, including changing settings. An author can edit pages, but can’t change settings for the wiki as a whole. A watcher is simply someone who can access private pages of the wiki.

Members you add must already have a Torchpad account; trying to add someone whose email address is not registered with Torchpad will result in an error.

Once added, a member can be removed by clicking Remove next to their name in the members list.

Export Your Wiki

If you want to take your wiki elsewhere, or just want a backup of it, you can download the Markdown files in a zip archive. Click Settings, and then click Export.

Export page
A zip archive is great as a backup of your wiki.

There are two options, but because Torchpad is still in beta, only Download Zip is available. Click that to download the zip archive containing all the Markdown files.

In the future, the Git Clone option will become available, allowing you to download the wiki as a git repository, including all the edit history for each page.

Conclusion

In this tutorial, I have shown you how to add and edit pages on a Torchpad wiki, publish the wiki, and add collaborators. A wiki can be useful in many different ways, and Torchpad makes it as simple as it could possibly be to make one. It may not have all the features of the more complicated tools, but it’s still possible to make a great wiki.

Advertisement