Markdown Style Guide for Shadow Academy Course Notes: Difference between revisions

From Wikipedia of the Dark Brotherhood, an online Star Wars Club
m (Phew)
No edit summary
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Introduction ==
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 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 a guideline outline how the course notes should be structured and how Markdown should be applied to them so they they appear as intended on the Shadow Academy website.


This document is maintained by the [[Headmaster]] and Praetor to the Headmaster.
This document is maintained by the [[Headmaster]] and Praetor to the Headmaster.
Line 6: Line 5:
== Generic Guidelines ==
== Generic Guidelines ==


=== Section names and numbering ===
=== Section names ===
Section names should ''clearly'' describe what the section is about. The first sections should be named "Introduction" and the last section should be named "Conclusion."
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.
 
Section headers should be numbered for easy reference following this scheme:
 
<pre>1 - Introduction
2 - Example Section 1
3 - Example Section 2
  3.a - Example Sub-Section 1
  3.b - Example Sub-Section 3</pre>
 
Third level sections should be avoided where possible. An alternative is to use quasi headings, which are italicized, under second level headings.


=== Point of view and tone ===
=== Point of view and tone ===
Like on a Wiki, all course note 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."
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.
Courses about "in-universe" topics should be written in the past tense.
Line 27: Line 16:


=== Spelling and grammar ===
=== 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 and checked for spelling and grammar errors.
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.
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 ===
=== 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.
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.


Line 41: Line 30:


=== Be comfortable with the syntax ===
=== Be comfortable with the syntax ===
Unlike other options, like HTML, Markdown is a very natural way of writing course notes. Notes that have been marked down with Markup can be easily read in their own right as stand alone documents. Chances are you have already either used Markdown on other websites (possibly without realizing it), and it is fairly similar to the syntax used on the DJB Wiki.
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.
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 ===
=== 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.
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.
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 ===
=== Header levels ===
Primary headings should be level 2 headers, they are achieved in Markdown as:
Primary headings should be level 1 headers. They are achieved in Markdown as:


<code>## 1 - Introduction</code>
<code># First Heading</code>


Secondary headings should be level 3 headers:
Secondary headings should be level 2 headers:


<code>### 3.a - Example Sub-Section 1</code>
<code>## Example Sub-Section 1</code>


Note that the number of "hashes" denote the level of the header. Like on the wiki, first level headers are too large and should be skipped in favor of second level headers.
Note that the number of "hashes" denote the level of the header.


=== Lists ===
=== Lists ===
<code>*</code>, <code>-</code> or <code>+</code> can be used to denote and item in a "un-ordered" list. In course notes it is preferred to use <code>*</code>, though it makes no difference to what is rendered for the students. For sake of constancy, there should always be one space (no more) between the symbol and the item in the list.
<code>*</code>, <code>-</code> or <code>+</code> can be used to denote and item in a "un-ordered" list. In course notes it is preferred to use <code>*</code>, 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.
To create a sub item in a list, simply indent that line.
Line 84: Line 73:
     viverra nec, fringilla in, laoreet vitae, risus.</pre>
     viverra nec, fringilla in, laoreet vitae, risus.</pre>


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


<pre>*  Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
<pre>*  Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Line 104: Line 93:


=== Images ===
=== Images ===
Images can either be linked directly into the body of the notes or given a name and linked to in a block at the end of the notes. In the interest of maximizing the readability of the course note's Markdown, it is preferred to list the urls to the images at the end of the notes.
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, alt text in square brackets and an id name in square brackets.


<code>![Alt text][id]</code>
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 <code>![stormtrooper]</code> as your image ID if you've already linked the word <code>[stormtrooper]</code> in the course notes.


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


<code>[id]: url/to/image</code>
<code>[id]: https://secureurl.com/image.png</code>


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


=== Hyperlinks ===
=== 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.
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:
Where you would like the link to appear:


<code>[Display text][id]</code>
<code>[Display text]</code>


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


<code>[id]: url/to/page</code>
<code>[Display text]: https://secureurl.com</code>


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


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


To italicize text, put one <code>*</code> on either side of the word or words.
To italicize text, put one <code>*</code> on either side of the word or words.
Line 156: Line 143:


=== Cheat and steal ===
=== Cheat and steal ===
Often, one of the best ways to learn is to look at (and borrow from) other peoples work. You can see the markdown used in any other Shadow Academy course, but adding ".text" to the end of the URL.
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.


<code>http://staging.darkjedibrotherhood.com/shadow_academy/courses/28.text</code>
<code>https://www.darkjedibrotherhood.com/shadow_academy/courses/172.text</code>


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.
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.
Line 169: Line 156:
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.
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.


[[Category:DJB Info]]
[[Category:Guides]]

Latest revision as of 23:55, 18 May 2021

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

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.