Markdown Style Guide for Shadow Academy Course Notes

This document is intended to be a guide for those writing Shadow Academy course notes and those who are readying them for inclusion on the Shadow Academy website (often the same person). This document will give an outline of how the course notes should be structured and how Markdown should be applied to them so they appear as intended on the Shadow Academy website.

This document is maintained by the Headmaster and Praetor to the Headmaster.

Generic Guidelines

Section names

Section names should clearly describe what the section is about. Do not use "Introduction" as your first header since it provides no information about the topic of that section. Introductory text may be placed before the first header.

Point of view and tone

Like on a Wiki, all course notes should, as much as possible, be of a neutral point of view. They should give facts, and if opinions are needed they should be balanced and from multiple "angles."

Courses about "in-universe" topics should be written in the past tense.

Any "out of character" courses, such as tutorials on using computer software, should be written in the present tense.

Spelling and grammar

Spelling mistakes and obvious grammatical errors can be jarring for readers. It also distracts from the professionalism of a document. English is not everyone's first language, so it is understandable that it is not easy for everyone to produce Course Notes that are 100% accurate, however at a minimum all notes should be run through a document processor like Microsoft Word or Google Docs and checked for spelling and grammar errors.

If possible, someone well versed in the English Language, and its nuances, should read over notes before they are made public.

Sex appeal: know when to break the Markdown Guidelines

While these guidelines set out to standardize how course notes are presented and "marked up," it is important to realize that these rules should not be followed to the letter in all cases.

If following these guidelines would make the notes look awkward, ugly or otherwise hard to read, they should be adjusted to give the student the best possible reading experience.

If you are ever unsure, ask a fellow faculty member or the Headmaster.

Markdown Guidelines

Be comfortable with the syntax

Unlike other options, like HTML, Markdown is a very natural way of writing course notes. Notes that have been formatted with Markdown can be easily read in their own right as stand alone documents. Chances are you have already used Markdown on other websites (possibly without realizing it), and it is fairly similar to the syntax used on the DJB Wiki.

The external links section below contains a number of links that you can refer to familiarize yourself with Markdown.

You can't irreversibly break something

There is nothing you can do with Markdown that will break the website or the document itself. Don't be afraid to play around with the syntax to get the course notes exactly how you want them.

If all else fails we can always go right back to the original document and start again, or see if there is a different revision we can refer back to, but in most cases removing the offending Markdown syntax will fix any issues.

Header levels

Primary headings should be level 1 headers. They are achieved in Markdown as:

# First Heading

Secondary headings should be level 2 headers:

## Example Sub-Section 1

Note that the number of "hashes" denote the level of the header.

Lists

*, - or + can be used to denote and item in a "un-ordered" list. In course notes it is preferred to use *, though it makes no difference to what is rendered for the students. For sake of consistency, there should always be one space (no more) between the symbol and the item in the list.

To create a sub item in a list, simply indent that line.

* First item
* Second item
  * Sub item under second item
* Third item

Renders

• First item
• Second item
  • Sub item under second item
• Third item

If an item spans multiple lines, they should be indented to match.

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.

An item can even be multiple paragraphs. Simply add an extra line in between lines within the item.

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.

Numbered lists are denoted by a number and a period (1.), note that Markdown does not care what number you supply, it will display the correct number based on what is in the list. When writing your course notes however, please accurately label the items in a numbered list for the sake of readability of your Markdown.

1. First item
2. Second item
3. Third item

Renders

1. First item
2. Second item
3. Third item

Images

In the interest of maximizing the readability of the course note's Markdown, images should be given a name and linked to in a block at the end of the notes.

Where you would like the image to appear in the notes, write an exclamation point followed by the ID in square brackets. Ensure that your ID is not exactly the same as the name for a normal link in the course notes. For example, do not use ![stormtrooper] as your image ID if you've already linked the word [stormtrooper] in the course notes.

At the end of the notes, include the full, secure (https) path to the image, like so:

[id]: https://secureurl.com/image.png

Note that in both of those examples, the ID must match in order for the image to show.

Hyperlinks

Hyperlinks are very similar to images, except that they are specified without an exclamation point in front of them. For the same reason as with images, their actual urls should be at the end of the document.

Where you would like the link to appear:

[Display text]

At the end of the notes, include the full, secure (https) path to the image, like so:

[Display text]: https://secureurl.com

Again, note that the IDs must match, they must also be unique.

Bold and italics

Bold and italicized text should be used sparingly to draw attention to important words or sentences.

To italicize text, put one * on either side of the word or words.

The quick brown fox jumps over the *lazy* dog

 The quick brown fox jumps over the lazy dog

To make text bold, use two *'s either side of the word or words.

The quick brown fox **jumps over the lazy dog**

 The quick brown fox jumps over the lazy dog

Quote and code blocks

Where you need to display a quote, start the line with a right angle bracket.

> This is a quote.

Where you need to display a block of code, for example in a programming course, indent the line by four spaces or one tab (spaces are preferred):

This is normal text.

    Write-Host "This is Code"

Cheat and steal

Often, one of the best ways to learn is to look at (and borrow from) other people's work. You can see the Markdown used in any other Shadow Academy course, by adding ".text" to the end of the URL.

https://www.darkjedibrotherhood.com/shadow_academy/courses/172.text

If you're ever looking over notes and wondering how the author managed to do what they did, add that to the address and you'll be able to see exactly how it was done.

External Links

• http://daringfireball.net/projects/markdown/
• http://en.wikipedia.org/wiki/Markdown

Conclusion

I hope that this guide has been clear and understandable, if you notice any errors or sections that need expansion please let the Headmaster know.