Markdown 102

Table of Contents

A Note on "DB Markdown"
A Picture is Worth a Thousand Words
- Secure Links and the Asset System
- Image Syntax
Be a Dear and Set the Table
Listception
All I See Now is Blonde, Brunette, Redhead
A Wise Man Once Said
I'd Say I'm 'True Neutral'
Linking Images (And How to YouTube)
Combining Emphasis
Conclusion

In Markdown 101, you learned the basics of presenting text using Markdown syntax for Headings, Emphasis, Lists and Links.

While this knowledge is enough to write serviceable reports, you’ll soon find yourself wanting to do more. This course will cover images, tables, nested lists, code blocks, quote blocks and some other useful tips.

A Note on "DB Markdown"

There are a few things that make the Dark Brotherhood’s implementation of Markdown different than the standard Markdown or the implementation on other sites. These differences shouldn’t hinder your use of the syntax, but may become apparent if you follow a Markdown tutorial from the Internet.

One of the main things you will notice is that all HTML has been disabled; this was by far one of the biggest things the Seneschal could do to increase the security of the website. It means you, as a content creator, lose a little bit of control and flexibility and have to rely solely on Markdown. To help with this, the DB’s implementation has some custom additions which will be pointed out as they are covered.

It should be noted that the Brotherhood specific additions to Markdown syntax will not work elsewhere on the Internet.

A Picture is Worth a Thousand Words

Secure Links and the Asset System

Before we get into how to insert images into your Markdown, you'll need to understand secure links and the Brotherhood's [Asset Management] system.

The secure nature of the Dark Brotherhood site means that any pictures need to be from a secure link. Many hosting sites will give you secure links. You can identify them because they will start with a https.

If you are in a position which is able to post news items, you may also use the Brotherhood's [Asset Management] system, which allows you to upload images for recurring use in reports, news posts and Shadow Academy courses. Once an image is uploaded, you'll be supplied with an asset identifier – like the asset:100_dblogo in the examples below – that you can use in place of a secure URL.

To save server space, you should only use this feature for images that are either used in multiple reports (headers, dividers, footers) or images that contain actual important information (infographics, charts, etc.). Gifs and one-off images that are only used on one or two reports should be uploaded to an external host such as [Imgur] instead.

The examples in this course will use the Brotherhood Assets system. The asset tag can be replaced with your own asset tag or a secure URL.

Image Syntax

At its most basic level, the syntax for images is almost identical to that of hyperlinks; the difference is that images are prefaced with an exclamation point.

For example, a hyperlink to the Dark Jedi Brotherhood website looks like:

EX1: Inline URL

[Dark Jedi Brotherhood](https://www.darkjedibrotherhood.com/)

Whereas showing the Brotherhood's logo would look like:

EX2: Inline Image URL

![DB Logo]([asset:100_dblogo])

Notice that there is still text within square brackets when creating images. This text isn't displayed, but acts as the "Alt Text" for the image.

Just as with links, you have several options for how and where to provide the links to your images.

Firstly, you can specify the URL in parentheses immediately following the Alt Text in square brackets. This is demonstrated in EX2, above.

Secondly, you can specify an ID or reference in a second set of square brackets, and then use the ID at the end of your document:

EX3: Referenced Image URL with Alt Text

![DB Logo][Pic1]


Lots and lots of filler text.


`[Pic1]: [asset:100_dblogo]`

Thirdly, you can forgo the ID, and use the alt text as your reference:

EX4: Referenced Image URL no Alt Text

![DB Logo]


Lots and lots of filler text.


`[DB Logo]: [asset:100_dblogo]`

You can use whichever method you find easiest. The Shadow Academy uses the third option (without the ID) for its ease of management of multiple images across a multitude of course notes.

n.b. In the second and third example above, you will notice backticks surrounding the final line in each. This is purely to ensure that the text there is displayed, and, when actually using these examples, you should not include the backticks.

Be a Dear and Set the Table

DB Markdown does provide the ability to create tables, though you're very limited in their design. You cannot specify borders, or cell width or padding. In most cases where you would like to present a complex table, I would suggest linking to a Google Sheet document, or taking a screenshot of the table from within a spreadsheet application and presenting it as an image.

A simple markdown table can be created as simply as this:

EX5: A Tidy Table

Header 1       | Header 2
-------------- | --------------
Row 1 Column 1 | Row 1 Column 2 
Row 2 Column 1 | Row 2 Column 2

Header 1	Header 2
Row 1 Column 1	Row 1 Column 2
Row 2 Column 1	Row 2 Column 2

Notice that the first line contains the heading for each column, separated by a pipe (|). On the next immediate line are dashes (-), again with a pipe denoting the columns. Finally, each additional line contains the data for each row of the table.

In this example, I have made sure that pipes line up in the code block for demonstration purposes. It is entirely cosmetic and makes it easier to read, but creating a much "messier" table will produce the same output.

EX6: A Messy Table

Header 1 | Header 2
--- | ---
Row 1 Column 1 | Row 1 Column 2 
Row 2 Column 1 | Row 2 Column 2

Header 1	Header 2
Row 1 Column 1	Row 1 Column 2
Row 2 Column 1	Row 2 Column 2

You may have noticed by now that the text following a table is placed immediately after it. There appears to be no way of forcing a line break after the table at the time of writing this course.

The line of dashes under the heading row can be used to specify alignment of the column through the positioning of colons.

:---- Aligns left

:---: Aligns center

----: Aligns right

EX7: Table with Aligned Columns

| Right | Center | Left  |
| ----: | :----: | :---- |
| 10    | 10     | 10    |
| 1000  | 1000   | 1000  |

Right	Center	Left
10	10	10
1000	1000	1000

In this example, I have included extra pipes on the outside of the table to frame it. Again, this is purely cosmetic, but can help some understand that it is a table when viewing in plain text.

The final note to make about tables is that the data values will honor some basic text formatting, such as bold and italics.

EX8: Table with Emphasized Data

Component | Price | QTY | SubTotal
:-------- | ----: | :-: | -------:
CPU       | $350  | 1   | **$350**
RAM       | $99   | 4   | **$396**
Graphics  | $500  | 2   | **$1,000**

Component	Price	QTY	SubTotal
CPU	$350	1	$350
RAM	$99	4	$396
Graphics	$500	2	$1,000

Listception

It's all well and good being able to create a list of items. One through ten, or a simple list of bullet points. But, what if one of those points needs to be expanded further? What if you need subitems on your list?

To denote a new layer in a list in Markdown, indent it with four spaces. You can mix and match ordered and unordered lists and continue to nest as far as required.

EX9: Lists within Lists within Lists

1. Item
    1. Sub-Item
        * Sub-Sub-Item
        * Sub-Sub-Item
            1. And back to numbers
            1. And back to numbers
            1. And back to numbers
        * Sub-Sub-Item
        * Sub-Sub-Item
    1. Sub-Item
        * Sub-Sub-Item
1. Item
    1. Sub-Item

Item
1. Sub-Item
  - Sub-Sub-Item
  - Sub-Sub-Item
    1. And back to numbers
    2. And back to numbers
    3. And back to numbers
  - Sub-Sub-Item
  - Sub-Sub-Item
2. Sub-Item
  - Sub-Sub-Item
Item
1. Sub-Item

All I See Now is Blonde, Brunette, Redhead

In this course, and Markdown 101, I make use of Code Blocks to demonstrate how the markdown code works. Code Blocks surround text (which is generally some sort of code) and applies code highlighting to it. To denote a code block, place 4 tilde (~) characters above and below the code in question.

~~~~

Code goes here

~~~~

For a non-Markdown example, here is a snippet from a c# program:

string s = p.ProcessName;
s = s.ToLower();
if (s.CompareTo("callista") == 0) // Is the process Callista?
{
    callistaFound = true;
}

Don't worry if you don't know the language. Looking at the colors of the text, you can see that different parts have different colors - this allows you to quickly identify common elements within the code.

A Wise Man Once Said

Have you ever noticed how some email clients quote the message you're replying to? Often times this is done with a right pointing angle bracket (>) and that is exactly how you quote text in Markdown. Begin the line of text being quoted with that character, followed by a space.

EX10: Single Line Quote

> A wise man once said: 'Education is the most powerful weapon to change the world.'

A wise man once said: 'Education is the most powerful weapon to change the world.'

You can span multiple lines within a quote. Just start each line with the appropriate angle bracket.

EX11: Multi Line Quote

> A wise man once said: 'Education is the most powerful weapon to change the world.'
> 
> Also:
> 
> A wise man once said that you don't get rich at work. You get rich by doing your homework.

A wise man once said: 'Education is the most powerful weapon to change the world.'

Also:

A wise man once said that you don't get rich at work. You get rich by doing your homework.

I'd Say I'm 'True Neutral'

I'd wager one of the main reasons you're taking this course is to learn how to align 'things.' Be it text or images, you need to set it where you want it to appear among the rest of your text.

While this syntax will work on the Brotherhood website, it won't work anywhere else on the web.

-> Center aligned <-

-> Right aligned

Left aligned <- (this is the default behaviour, but is included for completeness.)

->| Justified |<-

--> Float right

Float left <--

The difference between, for example, 'right aligned' and 'float right' is that aligned will display the text or image pressed up against the right of the page, but it will block all the space to the left of it and keep it blank, whereas float will allow the document text to 'wrap' around the floated element.

Generally speaking, you'd want to use align for text and float for images.

n.b. Where more than a few words were needed to demonstrate any of these alignment options, [Lorem Ipsum][dummy] dummy text was used.

Center Alignment

EX12: Center Aligned Image

Filler text


-> ![DB Logo]([asset:100_dblogo]) <-


Filler text

Filler text

DB Logo

Filler text

Right Alignment

EX13: Right Aligned Text

Filler text


-> Right aligned text


Filler text

Filler text

Right aligned text

Filler text

Justified Text

EX14: Justified Text

->| Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut elementum metus. Suspendisse nec metus in arcu consectetur pellentesque. Morbi ac lobortis nibh, ut malesuada turpis. Donec faucibus magna eu porttitor consequat. Aenean mattis, erat convallis mattis posuere, leo orci auctor nunc, vel egestas dui ligula vel ipsum. Morbi eget libero eu felis iaculis dictum. Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet. |<-

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut elementum metus. Suspendisse nec metus in arcu consectetur pellentesque. Morbi ac lobortis nibh, ut malesuada turpis. Donec faucibus magna eu porttitor consequat. Aenean mattis, erat convallis mattis posuere, leo orci auctor nunc, vel egestas dui ligula vel ipsum. Morbi eget libero eu felis iaculis dictum. Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet.

Float Right Example

EX15: Right Float Image

--> ![DB Logo]([asset:100_dblogo])


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut elementum metus. Suspendisse nec metus in arcu consectetur pellentesque. Morbi ac lobortis nibh, ut malesuada turpis. Donec faucibus magna eu porttitor consequat. Aenean mattis, erat convallis mattis posuere, leo orci auctor nunc, vel egestas dui ligula vel ipsum. Morbi eget libero eu felis iaculis dictum. Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet.

DB Logo

Notice the blank line between the image and the text, yet when the page displays, they both start on the same line.

Float Left Example

EX16: Left Float Image

![DB Logo]([asset:100_dblogo]) <--


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut elementum metus. Suspendisse nec metus in arcu consectetur pellentesque. Morbi ac lobortis nibh, ut malesuada turpis. Donec faucibus magna eu porttitor consequat. Aenean mattis, erat convallis mattis posuere, leo orci auctor nunc, vel egestas dui ligula vel ipsum. Morbi eget libero eu felis iaculis dictum. Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet.

DB Logo

Keeping It Tidy

Sometimes you need to ensure that your text or other elements don't display until they are horizontally below a previous element (usually an image.) You can use a clearfix (<-->) to achieve this.

EX17: Clearfix

--> ![DB Logo]([asset:100_dblogo])


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ut elementum metus. Suspendisse nec metus in arcu consectetur pellentesque. Morbi ac lobortis nibh, ut malesuada turpis. Donec faucibus magna eu porttitor consequat. Aenean mattis, erat convallis mattis posuere, leo orci auctor nunc, vel egestas dui ligula vel ipsum. Morbi eget libero eu felis iaculis dictum.


<-->


Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet.

DB Logo

Ut vel auctor enim, eget scelerisque tellus. Vestibulum egestas est tortor, a venenatis ante condimentum id. Nulla pellentesque eu ligula vel condimentum. Nullam ullamcorper tempus augue eget vehicula. Nam laoreet tortor turpis, non sagittis leo accumsan vel. Fusce id arcu et elit mattis vestibulum. Cras sed orci at tortor accumsan aliquet. Etiam quis lectus eu arcu tristique dapibus egestas eget turpis. Nulla vel arcu et quam adipiscing imperdiet.

Linking Images (And How to YouTube)

Instead of specifying clickable text in your links, you can specify a clickable image. Simply replace the text with the syntax for an image. This can very easily get messy and is an example of when to use references instead of supplying URLs directly.

A link: [Replace this text with an image](http://some-link.example.com)


An image: ![Someimage](https://example.com/image.jpg)


Combining the two: [![Someimage](https://example.com/image.jpg)](http://some-link.example.com)

I told you it gets messy. Using references, it looks more like this:

[![Pic1]][Link1]


`[Pic1]: https://example.com/image.jpg`
`[Link1]: http://some-link.example.com`

It is important to remember the exclamation point for the image, and that it goes inside the square brackets of the link.

You can use this technique to take advantage of the fact that YouTube automatically takes screenshots of videos and quickly link to them. If you take the following syntax, and change the two instances of YOUTUBE-VIDEO_ID_HERE you'll end up with an image of the video that can be clicked to be taken to YouTube to watch it.

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)

Combining Emphasis

Do you remember in Markdown 101, when it was mentioned that you can emphasise text with either asterisks or underscores? They can be used interchangeably, as it is the number of symbols which denotes whether the text is bold (two symbols) or italic (a single symbol.)

But what happens when you want to do both? In the simplest form, you can just bump the number of your preferred symbol up to three, but what happens if you're mixing and matching, maybe making the whole sentence italic and only part of it bold?

EX18: Messy Emphasis Combination

*This whole sentence is in **italics,** but **parts** of it are **bold.***

This whole sentence is in **italics,* but parts of it are bold.*

Notice how the website got confused as to what was meant to be bold, and didn't understand that the whole sentence should be italics? To make this easier, both for yourself and the website, I lean towards always using a single underscore for italics and double asterisks for bold.

EX19: Tidy Emphasis Combination

_This whole sentence is in **italics,** but **parts** of it are **bold.**_

This whole sentence is in italics, but parts of it are bold.

Conclusion

That's it. That's all you need to know to create amazing reports, news posts and Shadow Academy courses using Markdown. Go on now to the exam to test what you have learned. If there is anything else you would like to learn about Markdown, please email the Headmaster.

[Asset Management]: https://www.darkjedibrotherhood.com/admin/assets [Imgur]: https://imgur.com/upload [dummy]: http://www.lipsum.com/

Take the exam

Please log in to take this course's exam