Markdown
Talk on Markdown (which is itself written in Markdown)
Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004, designed to be easy to read and write, with a plain-text format that can be converted into structurally valid HTML. It simplifies the process of formatting plain text, providing a straightforward and human-readable way to create rich documents without the complexities of traditional word processors. Its simplicity and versatility have made Markdown a widely adopted standard for writing content across various platforms.
Here are some places you can use Markdown to write content:
README.mdfiles on GitHub/GitLab repositories. Issues, comments, and pull requests on GitHub/GitLab repositories also support Markdown formatting.- Jupyter Notebook Markdown cells.
- Chat Applications like Slack, Discord support Markdown formatting in messages. Reddit and Stackoverflow also support Markdown formatting in questions, posts and comments.
- ChatGPT writes all its responses in Markdown.
- Markdown at it’s core is nothing but a javascript library. Hence it is really easy to convert to HTML/PDF etc.
- Majority of all documentation for open source projects is written in Markdown.
- Specific Purpose Markdown Utilities:
- Jekyll is a static site generator that uses Markdown for content. It blends really well with GitHub Pages so you can host your own website for free. It is widely used by bloggers and developers to create static websites. It makes it really easy for bloggers to concentrate more on the content and less on the design. We will learn about this in future sessions.
- Marp (MARkdown Presentations) is a tool to make beautiful slide decks using Markdown. It helps in making professional looking presentations really fast. We will have future sessions on this as well.
- Mermaid is a tool to create diagrams and flowcharts using Markdown. It is really easy to use and can be used to create diagrams and flowcharts in no time. We will try to have future sessions on this too.
Markdown Syntax
Now we will learn about the syntax of Markdown.
Headings
# H1
## H2
### H3
#### H4
##### H5
###### H6
H1
H2
H3
H4
H5
H6
Paragraphs
This is a paragraph. It is separated from the next paragraph by a blank line. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus orci quam, congue ut est ac, sagittis vestibulum nulla. Integer ac.
This is a paragraph. It is separated from the next paragraph by a blank line. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus orci quam, congue ut est ac, sagittis vestibulum nulla. Integer ac.
Text Formatting
This is how we do **bold**, *italic*, ~~strikethrough~~, and ***bold italic*** text.
This is how we do bold, italic, strikethrough, and bold italic text.
Lists
Ordered Lists
01. First Item
02. Second Item
01. Rendering is done with correct numbering although I have put wrong numbering.
296. some other ordered point
- First Item
- Second Item
- Rendering is done with correct numbering although I have put wrong numbering.
- some other ordered point
Unordered Lists
we can either use *, + or - to create unordered lists. I prefer using -.
- First Item
- Second Item
- Third Item
- First Item
- Second Item
- Third Item
Nested lists
We can nest lists by indenting the sub items. Nesting ordered lists inside unordered lists and vice versa is also possible.
- First Item
- First Sub Item
- Second Sub Item
1. First Item
- First Sub Item
- Second Sub Item
- First Item
- First Sub Item
- Second Sub Item
- First Item
- First Sub Item
- Second Sub Item
Links
[This is a link to Google](https://www.google.com/)
[This is a link to Google which says "Google" upon hovering](https://www.google.com/ "Google")
[Relative links also work](../README.md)
This is a link to Google which says “Google” upon hovering
Images
Block Quotes
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.
Code and Syntax Highlighting
Markdown supports code and syntax highlighting, enhancing the readability of your programming examples. To denote inline code, wrap the code snippet with a pair of backticks (`). For instance:
Inline code examples: `var x = 10;` or `print("Hello, World!");`
Inline code examples: var x = 10; or print("Hello, World!");
Now, for multi-line code blocks, use triple backticks (```). Specify the language after the opening triple backticks for syntax highlighting. For a comprehensive list of supported languages for syntax highlighting, you can refer to this link. Here are examples in Python, Java, and C/C++:
No language specified:
def greet(name):
print(f"Hello, {name}!")
greet("Markdown")
Python Example:
def greet(name):
print(f"Hello, {name}!")
greet("Markdown")
Java Example:
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
C++ Example:
#include <iostream>
int main() {
std::cout << "Hello, Markdown!" << std::endl;
return 0;
}
Tables
Markdown allows you to create simple tables to organize data in a tabular format. The basic syntax for a table consists of pipes (|) to delineate columns and hyphens (-) to separate the header row from the content.
Basic Table:
| Name | Age | Occupation |
|--------|-----|---------------|
| Alice | 28 | Web Developer |
| Bob | 32 | Data Analyst |
| Carol | 25 | Designer |
This renders as:
| Name | Age | Occupation |
|---|---|---|
| Alice | 28 | Web Developer |
| Bob | 32 | Data Analyst |
| Carol | 25 | Designer |
Middle Aligned Table:
You can also align the content within the columns, such as center-aligning the numeric values:
| Name | Age | Occupation |
|:------:|:---:|:---------------:|
| Alice | 28 | Web Developer |
| Bob | 32 | Data Analyst |
| Carol | 25 | Designer |
This renders as:
| Name | Age | Occupation |
|---|---|---|
| Alice | 28 | Web Developer |
| Bob | 32 | Data Analyst |
| Carol | 25 | Designer |
Less Well-Formatted Table:
Even a minimal separator (---) between the header and content rows can create a table:
|Name|Age|Occupation
|---|---|---
|Alice|28|Web Developer
|Bob|32|Data Analyst
|Carol|25|Designer
This renders as:
| Name | Age | Occupation |
|---|---|---|
| Alice | 28 | Web Developer |
| Bob | 32 | Data Analyst |
| Carol | 25 | Designer |
While the last example lacks visual separation, it is still rendered correctly.
LaTeX Equations in Markdown
Markdown supports the inclusion of LaTeX equations, allowing you to seamlessly integrate mathematical expressions into your documents. To incorporate LaTeX equations, use the following syntax:
Inline Equations:
Enclose the LaTeX code within a pair of dollar signs ($) for inline equations. For example:
The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.
This renders as:
The quadratic formula is (x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}).
Display Equations:
For standalone, centered equations, use double dollar signs ($$). Here’s an example:
$$
\int_{0}^{\infty} e^{-x^2} \,dx = \frac{\sqrt{\pi}}{2}
$$
This renders as:
\[\int_{0}^{\infty} e^{-x^2} \,dx = \frac{\sqrt{\pi}}{2}\]Markdown will then convert the LaTeX code into beautifully formatted mathematical expressions, providing a seamless way to incorporate complex equations into your documents.
Inline HTML
Markdown allows the incorporation of HTML elements for more intricate styling or specific functionalities. Here are a couple of examples:
Horizontal Rule (<hr> tag):
You can use the <hr> tag to insert a horizontal rule:
Some content above the rule.
<hr>
Content below the rule.
Some content above the rule.
Content below the rule.
Styled Button Example:
You can also embed more complex HTML elements, like creating a rounded corner blue button:
<button style="border-radius: 5px; background-color: blue; color: white; padding: 8px 16px; cursor: pointer;">
Click Me
</button>