Markdown powerful text

Markdown is a great way to create text documents that are multipurpose and will last over time. Multipurpose because you can go from markdown to HTML for webpages very easily. Likewise you can go from markdown to MS Word or PDF documents easily. Markdown is a plain text document that does not depend on one particular app for formatting. Plus markdown files are small, really small.

Progress: Getting There!
52%

Why Markdown?

Markdown is a very simplified "language" for writing HTML. It was developed around 2003 and now many apps use Markdown. One of the advantages of markdown, much like modern web design, is that style and substance are controlled by different mechanisms. In web design your content (mainly HTML) is different from how content is styled (mainly CSS). This has several advantages. One of the main benefits is you can easily change the "style" on a web page without having to redo the content.

We also live in a world where content often needs to be developed for two audiences at the same time: websites and paper (or PDF) documents. Markdown makes it super easy to create for both formats at the same time.

I want you to use markdown in this course as it makes several things much simpler for me. I'll tell you about those "simpler things" later. But it's also a great tool for you to have up your sleeves. Typically it takes about an hour to learn about markdown.

Overview Video

Nicholas Cifuentes-Goodbody is the author of this 11 minute video is titled Markdown: Academic Writing in Plain Text. This is a wonderful introduction to markdown. He covers the academic benefits, and hows, for using markdown. Most people start using markdown for other reasons: it's a very simple way to write HTML code. That's right: it's a great way to develop web content. Virtually all markdown editors have a way to auto-translate from markdown to HTML.

Basic Syntax

The tutorial you do later (next section) will emphasize the same points, introduce others, and provide you with some practice. The purpose here is to introduce you to the most common syntax issues. The syntax code will show up with an orange background, whereas the rendered version (styled by CSS) will show up as it will appear on a final rendered document (whether that document be a web-page or a PDF).


Headers

Headers are headings. The provide the structural outline for any document. Making use of headers can be crucially important. The one exception may be with your reflections: you may not need more than one header for that document. Up to you.

Headers always go in order. There are 6 possible headers but you'll rarely need more than 3 levels. The first level header is always the "lead" or title of the document or webpage. The second level headers start to divide up the document into sections. Third level headers provide nuance within a second level area.

Indicating headers are simple. Use the "#" (number) sign then type the name of the header. If it's a header at level 6 then you would use 6 number signs followed by the name.

Here's code for some headers and basic text:

# Motivational Profile
Some introductory text goes here.

## Classroom Description
More text goes here

## Motivational Successes
More text here

## Motivational Challenges
More text here

I won't show you how this gets rendered as it will make this page look ugly! But headers are the outline of your document.


Bold

Make something bold by surrounding it with double-asterisks on either side. For example:

This is a **gorgeous** garden.

becomes:

This is a gorgeous garden.


Italics

Almost the same as bold, but just one asterisk on either side.

This is a *gorgeous* garden.

becomes:

This is a gorgeous garden.


Line Breaks

In an app like MS Word each line break (or return) creates a new line of vertical spacing in the document. Not so with Markdown. This is very important to understand. This means you don't need to be careful with line breaks (i.e. how many) but you do need to make them in order to indicate a new paragraph. After the text phrase below I entered 3 line breaks! It would not matter if I had entered 1 or 20 line breaks, the rendered text would look the same.

this is a line.


Shows up as:

this is a line.


New Lines

Most of the time you don't care about creating new lines. Just let the text flow as it will. But sometimes, like with poetry, you want to indicate that a line ends at a specific point. In order to do this place two spaces at the end of a line. Then press return to start the next line. Again ... you will rarely need this. In the example below I put in 2 spaces (or more) at the end of each phrase.

a boy went to the lake  
and then he found some fish   
he liked them a lot  

Shows up as:

a boy went to the lake
and then he found some fish
he liked them a lot


You will probably use links a lot. There is a very easy to way to structure them:

[name of link here](fullURLhere)

So if I wanted to provide a link to the primary jazz radio station in Paris I would put as code:

[TSF Jazz in Paris](https://www.tsfjazz.com)

The resulting syntax would show up in a previewer or exported document as:

TSF Jazz in Paris

As you know, sometimes links are super long. By putting in your chosen name for the link you can create something that is intelligible to everyone.

Lists

Lists are used a lot and you will probably write a few lists in your submissions for this course. The way markdown handles lists is both simple and wonderful. But to understand this process I'll make some distinctions between: ordered, unordered, and nested lists.

Important Note: The exact look and feel of a list will always be controlled by the CSS used. This can result in different indentation amounts, how bullets are displayed, and much more. But the CSS used on this website is what you'll in your work. P.S. Don't worry about the CSS!


Ordered Lists

An ordered list is a numbered list. If you are using a dedicated Markdown app (e.g. Typora) then it is likely the app with auto-advance the numbering when you press the return key. To start an ordered list type a number then period then space to begin.

A typical ordered list will look like this:

  1. first thing
  2. second thing
  3. third thing

What's interesting is that with markdown it does not matter what numbers you use as long as you introduce each list item with a number then period then space. That means this markdown:

33. an idea
4. more ideas
535. funny ideas

Will be rendered like this:

  1. an idea
  2. more ideas
  3. funny ideas

Unordered Lists

An unordered list is a bullet list. If you are using a dedicated Markdown app (e.g. Typora) then it is likely the app with auto-advance the bullets when you press the return key. To start an unordered list type a dash then space to begin.

Here's the code for an unordered list:

- first thing
- second thing
- third thing

And that unordered list will look like this:

  • first thing
  • second thing
  • third thing

Switching List Types

If you want to change the type of list you are creating from ordered to unordered (or visa versa) all you need to change is the very first list indicator. So this markdown code:

- my idea
3. other ideas
4. best ideas

Will be rendered as:

  • my idea
  • other ideas
  • best ideas

Nested Lists

Nested lists occur when you have more than one level to the list. You can mix ordered and unordered types within a nested list. To nest items you will need to indent them.

Here's an example of the markdown syntax for a nested list:

33. the big idea
    - i need to brainstorm this
    - create a list
3. prototype building something
    - can I build this well?
    - how long will it take?
55. evaluate the idea
    4. do I give up?
    7. worth developing within 6 months?

Is rendered as this:

  1. the big idea
    • i need to brainstorm this
    • create a list
  2. prototype building something
    • can I build this well?
    • how long will it take?
  3. evaluate the idea
    1. do I give up?
    2. worth developing within 6 months?

Images

Optional. If you want to include images in any of your writing in this course then use the HTML snippet provided below. What this really means is you'll need to use images that live on the web somewhere. This is all due to the original purpose of markdown: to make it much easier to develop web content.

<img src="fullURL-to-image-here" width="100%" />

For example I know one image has this web address:

https://mathewusf.com/motivation-warehouse/flow-channel1.png

So using the code above you can see the resulting snippet below:

<img src="https://mathewusf.com/motivation-warehouse   
/flow-channel1.png"    
alt="flow diagram" width="100%" />

And here's what it will actually look like on a published page (web or other):

flow diagram

Note: The 100% in the code is important as it tells someone that the image should take up 100% of the available space. Depending on the resulting format available space can be bigger or smaller. For example, think about resizing the width of your browser.


An image may already exist on the web, but what if you have one and it only exists on your computer somewhere. What to do? There's a very cool trick. In the Share section go to your personal folder. Upload the image(s) you want to use. Notice that to the right of every item there is first a little download icon. Then just to the right of that is a share icon. Click that share icon and a web-based address for the image will be copied. Use that in your HTML snippet.

Tables

Optional. You do not need to do this part of the mini-course. But if you think you might want to create tables then the information here will be crucial. I want to emphasize that markdown content can easily be translated into HTML. That means a markdown table will look good on a website! (The CSS for that table is determined by other things.)

Tables are very effective displaying compare and contrast information. For instance, when comparing various theories of motivation a table might be useful.

If you want to see an example of a markdown table (with CSS that I specifically chose for this website) then check out The Modules tab on the Syllabus page.

Nicholas Cifuentes-Goodbody is the presenter once again. Markdown tables may look cumbersome, but in the last 25% of the video he shows you a super easy app for creating these tables: TableFlip. You can download a demo. The app costs $10.

Syntax Tutorial

Complete the CommonMark interactive tutorial (link provided below). There are two sections of the tutorial that you should not do: Images and Code. Code just isn't important to you. Images, while it may be important, is flawed in how they are done in Markdown. I have a special section on images later on this page.

Interactive Markdown Tutorial


Syntax Quick Cheat Sheet

The same folks provide a nice & easy syntax review at the page linked below. It's short, it's gives various options, and it's a great quick refresher.

Syntax Overview

Unintuitive Bits

There are a few unintuitive parts of markdown that are actually big benefits. I have already stated all these points early, but let me go through them here to emphasize the difference between markdown versus a regular word processor.

Line Breaks

In a Word document (e.g.) each additional line break (or return) adds more vertical space between two portions of a document. Not true with markdown. Add as many line breaks as you want! To start a new paragraph you definitely need a line break. But even if you have 5 line breaks you'll still end up with the appropriate spacing for a new paragraph.

Lists & Line Breaks

The one exception regarding line breaks is lists. Any list needs to have a line break before it begins and a line break once it ends. Otherwise things will look funky.

Lists & Ordering

If you start a list with 1. (and a space) then the whole list will be ordered (i.e. numbered). If you start a list with a - (and a space) then the whole list will be unordered. This means if you start with a numbered list but later change only the first item to a dash (instead of a number) then the complete list will change to unordered (i.e. a bullet list).

Applications

You can not create a markdown document using a regular word processor like MS Word. Word processors enter in a lot of under-the-hood "stuff" that creates confusion when writing for the web or creating clean documents. Instead you'll need a markdown-friendly application.

There are a number of good apps for writing Markdown. I am going to suggest a couple of free options that work on both Macs and Windows. But if you want to use something else that's fine also. You can also use TextEdit (Mac) or NotePad (Win) to write Markdown.


StackEdit

This app is a web-app so it will work anywhere. The resulting file you can download as a TXT file.

StacksEdit site


Typora

This app is currently in a long beta-testing phase and thus is free for now. It works on Macs and Windows. One advantage of Typora is that you can designate a folder for all your Markdown files and they show up in Typora in a sidebar area. This makes it a bit easier to find stuff.

Typora app


Other Applications

I provided info on free cross-OS applications. Probably one of those two will work well for you. You can also use TextEdit (Mac) or NotePad (Win) to write markdown. Neither app provides any markdown previewing: but that becomes much less necessary over time. In addition here's some additional apps that I've found really useful.

  • Multimarkdown Composer (Mac). This is my personal choice for writing markdown. Integrates nicely with Marked 2 (see Preview section). Primarily good for writing longer documents. Brilliant table of contents feature makes it super-easy to rearrange you document's section ordering. Other nice features. Comes is regular and pro versions.
  • Bear (Mac, iPad, iPhone). Note-taking app that works via markdown.
  • Scrivener (Mac and Win). Not a dedicated markdown app, but you can export all your work as markdown. However there is no preview capability.
  • MarkdownPad (Win). Seems to be the best Windows markdown editor. Free and pro versions.

Extensions

Markdown files can have a couple of different extensions associated with the file. You can use either MD or TXT. Either one is fine. So if your document is titled Gumok Reflection 3 then the proper full name could be either:

  • Gumok Reflection 3.md
  • Gumok Reflection 3.txt

Extensions are very important when we share things via the Share section of the website. Without an extension on an uploaded document I won't know what type of file it is (text, image, and so on).

Previewer

Optional. Several apps come with built in previewers. I especially like using Marked 2. It's a Mac-only app and costs $14. The developer (Brett Terpstra) has also created a nice set of YouTube tutorials about using this app: Marked 2 Tutorials.

However, probably the best tutorial is done by Nicholas Cifuentes-Goodbody and is provided below.

Starter Documents

I am providing some generic starter documents for writing Reflections and or other assignments. The documents have starter material (duh) but also list some key syntax within them so you can use as an easy reference. Just delete those bits you don't end up using.

When you download a document first make a copy of the relevant one and then rename for your purpose (reflection, proposal, etc.). Each download comes with 2 versions: TXT and PDF. The PDF is provided so you can see how the page will get rendered using the CSS I've chosen to use for my website and PDFs.


Reflection Starter

This is the one you'll use every week.

Reflection Starter


Generic Starter

This is one you'll use at times. You will use for your first motivational profile assignment in Module 1. Useful to use for your Classroom Module that you create. And perhaps for other documents.

Generic Starter

© 2019 Mathew Mitchell Contact Me