Wiki Editing

Getting started

Cloning a wiki into your editor:

gcl devops.wiki
cd devops.wiki

Now you can edit and version control just like how you edit code in your editor with git.

Things to remember

Images

If the wiki has images, make sure images are in the repo itself (this important for backups and editing).

Highlighted Codeblocks

Make sure "fences" have labels (sh, text, ruby, etc). For example if you are going to include a python snippet in triple backticks (```...```), prefix the triple backticks with the language fence. For example:
```python
...
```
This will make markdown use the appropriate syntax highlighting for the language. More on highlighted codeblocks.

Links

Rember to include links to other pages that are relevant. Include relevant links within the page as well. Link syntax:

[<This is the link text>](<URL>)

or if within a page you can use the anchors created for all sections with #, ##, ...

#<anchor target>


[<This is the link text>](#<anchor target>)

Avoid long lines

When writing a wiki, hit return, don't write one long line. Long lines makes it difficult to diff changes made across commits. Consider two diff output examples:

-here's an example of a line that's way too long. It will be annoying to diff. It'll just show that one line's been changed, when instead, what we want is to have a more ganular view of the diff. We get a granular view of the diff when it is spread across more lines, rather than one really long one like this
+here is an example of a line that is too long. It will be problematic to diff. It will just show that one line has been changed, when instead, what we want is to have a more ganular view of the diff. We get a granular view of the diff when it is spread across more lines, rather than one really long one like this

vs

-Here's an example some text that if it were one line
+Here is an example some text that if it were one line
 it would be too long. It will be annoying to diff in
-that case. But since it is multiple lines. It will show
+that instance. But since it is multiple lines. It will show
 the diff at a more granular level, making it easier
-to compare with other commits.
+to compare with other edits.

The first example is all one long line. When we edit it and then look at the diff, it is not helpful in illustrating what has been edited. In the second example however, you can see much more clearly where changes were made.

When editing and collaborating on a wiki think of it like a program more than an mail message. You make edits and commit them. You can diff the commits to see exactly how things have changed.