Markdown is a simple markup language that is becoming extremely popular for documenting APIs. It can be used by many tools. It works like HTML, but it's much simpler and easier to read. For this course, you are going to be using Markdown for documenting JSON and XML. This video explains how to use it.
- [Instructor] This lesson covers Markdown which is a simple markup language. As part of this course, you'll be asked to write documentation. Markdown is becoming a popular way to write API documentation, so I decided you should learn enough Markdown to use it for the hands-on exercises. What is Markdown? It's a markup language like HTML is, but it's much simpler. It's very easy to learn, and it's much easier to read than HTML. It's used in many content tools such as Sphynx, Jekyll, GitHub, and ReadMe.io just to name a few.
Here is a little more information about Markdown. Special tools read in Markdown and convert it to HTML. Markdown has no style information which means that it's the tool that actually controls the final look and feel. There are different Markdown flavors. If there's something you want to do in Markdown that's not supported by that flavor, then just add the HTML to do it right in the Markdown content. Now I'll show you how Markdown works. Usually, lines together are considered part of the same paragraph. I say usually because some Markdown flavors handle line breaks differently.
So if you want a new paragraph, put an empty line between the lines of the different paragraphs. Here's an example. The first two lines end up in the same paragraph. But the third one has an empty line before it, so it's a new paragraph. Start a line with one or more hash marks to indicate headings. The number of hash marks indicates the heading level. Here we have three headings called Heading 1, Heading 2, and Heading 3 with levels one, two, and three, respectively. Bold and italics are easy in Markdown.
Surround text by single asterisks for italic and double asterisks for bold. You can see how that looks in this example. Monospace fonts are good for showing code concepts. To use a monospace font, surround the text with backticks which are backwards single quotation marks. You can see in the example the word "code" has each letter taking up the same width. Lengths use square brackets followed by a parentheses. The square brackets contain the text to be displayed, and the parentheses contain the URL for the link.
The URL can be either local or remote. This example shows a sample link. Images are very similar to links, but they start with an exclamation point. The text in the square brackets is optional, and it becomes the image's alternate text. The picture's URL is in parentheses, and it can be remote or local. The example shows an image from a local file with kitten as the alternate text. Unordered lists are lists with bullet points. These are very simple.
Just start with an asterisk or a dash for each item in the list. In the example, either text will give you a bulleted list. Ordered lists are numbered. These are also very simple. Just start each item with a number followed by a period. It actually doesn't matter what that number is. So for example, this list goes one, two, 10, and six in the Markdown. But when it's turned into HTML and displayed, it reads one, two, three, and four. Tables are the most complex part of Markdown that I'll show you.
Use pipes which are the vertical lines to separate columns. And use a special row of dashes right after the header row. Note that the pipes don't have to line up nicely. The Markdown to HTML tool will align everything for you. It's easier to understand when you see an example. Here's a table with two columns for name and definition. The second row contains the dashes. Then there are two rows that are part of the table. You can see that the pipes don't line up, and that's okay. Often there's more than one way to do something in Markdown.
For example, you can also create headings for level one by putting a line of equal signs under the heading and then put dashes under a heading for level two. You can write Markdown in any text editor. The easiest way to see what your Markdown looks like is to use an online Markdown editor. Just search "online Markdown editor" to find a free one. We will use StackEdit in this course. Okay, let's bring up StackEdit and I'll show you Markdown in action. I'm going to start by clicking "Start writing now!" If there's any text in here, I'll delete it.
So I'll start out blank. Okay, so I'm going to start by creating a header. I'll call it Peanut Butter. And you can immediately see the header show up on the right side. I'll write a little bit of text. I'll say "Peanut Butter is delicious". And then to make it bold, I can put asterisks on either side, and you can see that it shows up bold on the right side. So that's heading number two. Let's add one that says "How to make".
And I'll do an ordered list. So, first is "Crush peanuts". Second step is "Spread on bread". And you can see that that shows up on the other side. I'll add another heading two that says "Types", types of peanut butter. And let's put in a table now. So the top line is going to have the different columns. I'll have a Type and whether kids like it or not. Again, I need to have a line in between the very top line and the ones that follow.
And let's do Smooth. Yes, they like it. Crunchy, no they don't. And you can see on the right side again that the table is being created. So you can see it's really easy to create a simple Markdown document in StackEdit. If you need some references on how to use Markdown, they can be found easily on the web. The original flavor is on the Daring Fireball website, but that flavor doesn't include tables.
I'll show you what that website looks like. Here is the documentation for the original flavor of Markdown that's on the Daring Fireball website. And this is the documentation page for the GitHub flavor of Markdown.
- The purpose of documentation
- Data types
- Structured data
- Writing JSON and XML
- Documenting one-level JSON responses
- Documenting nested JSON responses
- XML attributes and examples
- Documenting XML
- Structuring data documentation