Most formatting in Wikity is done with the WordPress editor. You can add pictures, indent blockquotes, bullet lists, and soon (if we can figure out how to do it safely) embed content from places like YouTube.
However there are a few differences in Wikity syntax, especially around linking, and these differences are crucial to understand. If you don’t follow the special Wikity method of linking, your content will not be easily reusable by others and may even break our federated web. So read up and follow these simple rules.
- Use Double Brackets for Wikilinks
- Don’t Put External Links in Paragraphs
- Use Cite Keyword for External Footnoting
- Use Four Dashes to Create an Annotations Section
Use Double Brackets for Wikilinks
Link to other pages on your own site and other Wikity sites by using the standard wiki syntax like so:
To make a new page, the easiest way is to make a link to the non-existent page and click it. This will prompt you to create a new page with that name.
It is really important that you link to other wiki pages in this way, and not by using traditional hyperlinks. Hyperlinks will break fork-ability. Breaking forkability is bad.
The rest of this tutorial can wait if you want. The only absolutely required piece is Wiki Linking.
Don’t Put External Links Inside Paragraphs
This is less important than than the wiki link advice, but still important. When people browse wiki, the assumption is that links internal to paragraphs, like this one to Free To All, link to other wiki pages. This is an established wiki style. Browse Wikipedia for a bit and you will see what we mean. (Link)
Wikipedia style actually doesn’t allow any external links until the references section. We’ve come up with a compromise. If you really need to link to something external that is referenced in a paragraph, link to it at the end using Markdown Syntax. Here’s an example.
Here’s what that would look like in context.
That syntax is Markdown, a popular markup language you can look up on the Google. You can use the link word however you like (here we used it to note the resource was on a site called bavatuesdays), but we recommend it be a single word. Since the paragraph preceding it generally explains the context, and a hover shows the destination, we often use the keyword to indicate what sort of resource it goes to — a pdf, an HTML document, a Google Books citation. But if you want to link it as (bavatuesdays), knock yourself out.
Many people on Wikity use the following link words:
- “link” for a link to to a resource mentioned in the previous paragraph.
- “source” to link to the source of a blockquote or other used resource, such as a data table.
- “cite” for a link to supporting documentation for a claim.
Sticking to this format gives the reader more information on what the link means, and helps them decide whether to click on it. It also reduces the visual clutter of links, and reduces issues for people using screen readers.
These three keywords (link, source, and cite) are interpreted a bit differently than others, and presented with surrounding parentheses. Here’s an example of what that looks like:
In a recent post on Vox, reporter German Lopez questions whether there is any real crime wave at all. As she points out, if you pull apart any average, there will be random ups and downs, and that may be all that is happening here. (Link)
Use Cite Keyword for External Footnoting
Let’s dig into the cite keyword a bit more. Sometimes you may want to get an external reference closer to a clause, for instance when citing a disputable fact. Here’s an example of how to do that.
and here’s how that looks on the page to the viewer:
As Braithwaite notes°, shame can be useful, but it can also lead to recidivism.
Note the style here is the same as the external link syntax, but here we’ve used the keyword “cite”. Using the cite keyword instead of something like html, pdf, or bavatuesdays creates a little degree symbol superscript. This functions semantically as a footnote, signalling that support for this statement can be found by clicking the degree symbol, but it’s not necessary to understanding.
If the URL in the paragraphing is too messy to work around, you can use Markdown’s keyword syntax, which allows to to reference a keyword and put the link further down in the document.
Use Four Dashes to Create Annotations Section
Wikity pages, by convention, are split into two sections. The first is the “article” — a tight treatment of a single idea or subject. The article should be relatively self-sufficient: someone should be able to read the article and learn something without having to click around and see what the context of the article is.
The bottom section, which we are currently calling “annotations and associations”, suggests places to continue your journey. Here we put links to related articles on wiki, as well as links to external resources. Occasionally we also put notes on the page’s content, things like “To do: check claim about gun violence, and add link if true.”
To create the annotations section, place four or more dashes on a single line at the bottom of the page, like so:
To the reader this will look like this:
We’ve found that having this separate section for annotations is important to the culture of federated solutions like Wikity — it allows people a low-stress way to contribute to an article without having to touch the body of it. Annotations and Associations on your page also help guide readers to other things that might help them.