Wagn avoids making users "mark up" text with weird characters (like {[*-]}...) whenever possible. This step and the next explore the two main exceptions: links and nesting.
Both links and inclusions are special because they are references to other cards (or webpages), which means we need to do two things at once: (1) identify another card, and (2) put it in context on this card. All web links do that — (1) point to another web page, and (2) label that page.
Unless there's a good reason to do otherwise, Wagn tries to stay as close as possible to best practices. The wiki world doesn't always have agreed-upon best practices, but there is certainly a best-known practice: the one used in Wikipedia. Ours is very similar. The basic link mark-up is described in detail the links card:
Wagn makes it very easy for you to link to other cards in Wagn, or to other websites. These links are tracked as references and can be queried using the Wagn Query Language (CQL).
Example
[[Wagn News]] --> Wagn News
[[No Such Card]] --> No Such Card
[[Installation | How To Install a Wagn]] --> How To Install a Wagn
[[/recent | Recent Changes]] --> Recent Changes
[[http://www.grasscommons.org | Grass Commons]] --> Grass Commons
How To
Card Links
[[cardname]]
[[cardname | text]]
Direct Links
[[http://website.com | text ]]
[[/account/signup | text ]]
(autodetect)
Notes
- Leading and trailing whitespace is optional, so [[link|name]] is the same as [[ link | name ]].
- To actually show double brackets (for example in documentation), start with a backslash. So \[[Wagn News]] shows up as [[Wagn News]].
- Card links can use contextual names.
- You can also use nesting inside links to create contextual web addresses or to set contextual form content. However, it can cause problems to put inclusions inside the left side of named links. Inclusions on the right side of the pipe (|) generally don't cause problems. You can even put images there, doing things like [[ Philipp | ]].
- See links for examples.
Links within Wagn
To make a link to another card in Wagn, just put the link between double brackets. For example, [[Wagn]] gives you this link:
WagnYou can even link to a card that doesn't exist yet. The link will show up red, and anyone can just click on it to create the card. So [[I don't exist]] results in:
I don't existLinks to plus cards work the same way. [[Wagn 0.13+blog]] gets:
Wagn 0.13+Blog
If you want the text of the link to be different from the name of the card it's linking to, you use a vertical pipe after the link, followed by the text. So [[Aaron Nelson|IT hero]] shows up as:IT hero
There is a great deal more power possible with Wagn's internal links. See web address for everything and setting default content with links.
Links outside Wagn (or to another Wagn)
Any web address you enter will automatically become a link:http://grasscommons.org/Again, if you want the text of the link to be different, you use double brackets and put a vertical pipe after the link, followed by the text. [[http://www.grasscommons.org|Grass Commons]] results in:
Grass Commons
Escaping links
If you want to use double brackets without creating a link (for example in documentation), put a backslash just before the double brackets. For example, \[[this isn't a link]] appears as:
[[this isn't a link]]
Tips
- Are you linking to a card with a name that's long or that you're not sure of the wording/spelling? Just start typing the name of the card in the navbox. Then use the arrow keys to select the card from the auto-complete menu, select all, and copy.
Discussion
I would be interested in knowing whether there are ways to automatically link some text expressions. For instance each time I write "Grass Commons" then the link is automatically generated, be it to another wiki page or an external link. This function exists in many wikis...
What we have ticketed in this regard is optional WikiCase auto-linking. Then you could write GrassCommons and it would automatically link to Grass Commons.
--John Abbe.....Thu Sep 24 16:51:04 -0700 2009
Ah, and the tickets link below doesn't find anything, 'cause we're tagging with "linking", so see linking+tickets for item
--John Abbe.....Thu Sep 24 16:52:35 -0700 2009
[trishsprings]
--TrishSprings.....Mon Jun 18 06:41:09 +0000 2012
Let's have a go at it. Open up the links+Sandbox card below, and try creating the following links:
Now let's explore one of the great innovations of wiki: linking to a card that doesn't exist, and then creating it. Below is a list of three cards, none of which should exist. Unless someone else created them, you should see red links:
When you click on one, it will offer to let you create that card. Go ahead, try it. Be sure to add a little text in the content, and then come back here and reload this page. You will notice that the color of the link has changed. Click on it to see your newly created card. Now delete that card. To do that, click on the "Edit" tab, and then click on "Delete" in the lower right corner. Reload this page one more time. Red again, right?
Technically, the card hasn't been entirely deleted, it's just in the trash. If you click on that same link again, you'll see that the text you entered last time is still there in the Changes tab. The idea is to make it really hard to lose work! To keep things clean for the next user, go ahead and click on the red link to "create" it again, erase all the content and save it blank, and then delete it again. When you're finished, all the links above should be red. (We just included more than one link in case more than one person wanted to use this at the same time).
There's another way to create new cards. If you click on "New Card" on the menu at the top of the page, you will see a new card interface much like the ones you saw after clicking the red link, except without a name yet. You don't actually have to save the new card, but look at the menu next to "card type" (it's set to "Basic" by default). Try choosing, for example, "Image", "PlainText", or "Company" and you'll see the editor changes right away.
In Wagn, links aren't just part of content, they're also part of structure. Links are tightly tracked and can be queried.
So it's important to keep link quality high. If someone changes the name of a card, we need to make sure the links are still correct. So we offer the user the chance to change all the links at the time of the update, and that change itself is tracked.
Our mixture of link and inclusion markup with WYSIWYG (What You See Is What You Get) rich text editing is also pretty unusual. The idea is to hide as little as possible, and to give special emphasis to links and inclusions, on which we are able to build our structure.
On to the next step:
Back to Become a Wagneer