knowledge/technology/files/Markdown.md

obj	mime	extension	wiki	website	rev
format	text/markdown	md	https://en.wikipedia.org/wiki/Markdown	https://www.markdownguide.org https://commonmark.org	2024-03-08

Markdown

Markdown is a lightweight markup language that provides a simple and human-readable way to format plain text.

Syntax

Basic Syntax

Headings

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).

# Heading 1
## Heading 2
### Heading 3

Paragraphs

To create paragraphs, use a blank line to separate one or more lines of text.

Line Breaks

To create a line break or new line (<br>), end a line with two or more spaces, and then type return. Alternatively you can use inline html with the <br> tag.

Emphasis

You can add emphasis by making text bold or italic.

To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.

**Bold** text

To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.

*Italic* text

To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.

***All at once** text

Blockquote

To create a blockquote, add a > in front of a paragraph.

> My blockquote

Blockquotes can be nested. Add a >> in front of the paragraph you want to nest.

Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.

Lists

You can organize items into ordered and unordered lists.

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

1. First
2. Second
3. Third

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

- First
- Second
- Third

Code

To denote a word or phrase as code, enclose it in backticks (`).

At the command prompt, type `nano`.

Horizontal rules

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

Links

To create a link, enclose the link text in brackets (e.g., [Duck Duck Go]) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)).

My favorite search engine is [Duck Duck Go](https://duckduckgo.com).

Reference-style links are a special kind of link that make URLs easier to display and read in Markdown. Reference-style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere else in the file to keep the text easy to read.

The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds the text that should appear linked. The second set of brackets displays a label used to point to the link you’re storing elsewhere in your document.

The second part of a reference-style link is formatted with the following attributes:

1. The label, in brackets, followed immediately by a colon and at least one space (e.g., [label]: ).
2. The URL for the link, which you can optionally enclose in angle brackets.
3. The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.

This is my [reflink][reference]

[reference]: https://myurl.com

You can place this second part of the link anywhere in your Markdown document. Some people place them immediately after the paragraph in which they appear while other people place them at the end of the document (like endnotes or footnotes).

Images

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. The syntax is identical to links but with a ! at the start.

Escaping characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\) in front of the character.
You can use a backslash to escape the following characters.

Character	Name
|backslash
`	backtick
*	asterisk
_	underscore
{ }	curly braces
[ ]	brackets
< >	angle brackets
( )	parentheses
#	pound sign
+	plus sign
-	minus sign (hyphen)
.	dot
!	exclamation mark
|	pipe

HTML

Many Markdown applications allow you to use HTML tags in Markdown-formatted text. This is helpful if you prefer certain HTML tags to Markdown syntax. For example, some people find it easier to use HTML tags for images. Using HTML is also helpful when you need to change the attributes of an element, like specifying the color of text or changing the width of an image.

Extented Syntax

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column. For compatibility, you should also add a pipe on either end of the row.

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

Math

To add mathematical formulas, use LaTeX syntax enclosed within dollar symbols.

Formula: $E = m * c^2$

Fenced Code Blocks

To create code blocks use three backticks at the start and end of the code block (``` ```).

Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language directly after the backticks on the first line of the fenced code block.

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([^1]). Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.). You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, block quotes, and tables.

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

Heading IDs

Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

### My Great Heading {#custom-id}

The HTML looks like this:

<h3 id="custom-id">My Great Heading</h3>

You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by the custom heading ID. These are commonly referred to as anchor links.

Markdown	HTML
[Heading IDs](#heading-ids)	<a href="#heading-ids">Heading IDs</a>

Strikethrough

You can strikethrough words by putting a horizontal line through the center of them. The result looks like this. This feature allows you to indicate that certain words are a mistake not meant for inclusion in the document. To strikethrough words, use two tilde symbols (~~) before and after the words.

Task Lists

Task lists (also referred to as checklists and todo lists) allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content. To create a task list, add dashes (-) and brackets with a space ([ ]) in front of task list items. To select a checkbox, add an x in between the brackets ([x]).

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

Highlight

This isn’t common, but some Markdown processors allow you to highlight text. The result looks ==like this==. To highlight words, use two equal signs (==) before and after the words.

I need to highlight these ==very important words==.

Hacks

Center

Having the ability to center text is a necessity when writing a paper or a report. Unfortunately, Markdown doesn’t have any concept of text alignment, so this must be done with HTML and CSS.

<p style="text-align:center">Center this text</p>

Color

Markdown doesn’t allow you to change the color of text, so again we need HTML and CSS.

<p style="color: red">This text is red!</p>

Comments

Some people need the ability to write sentences in their Markdown files that will not appear in the rendered output. These comments are essentially hidden text. The text is viewable by the author of the document, but it’s not printed on the webpage or PDF. Markdown doesn’t natively support comments, but several enterprising individuals have devised a solution.

To add a comment, place text inside brackets followed by a colon, a space, and a pound sign (e.g., [comment]: #). You should put blank lines before and after a comment.

Here's a paragraph that will be visible.

[This is a comment that will be hidden.]: # 

And here's another paragraph that's visible.

Image Size

The Markdown syntax for images doesn’t allow you to specify the width and height of images. If you need to resize an image and your Markdown processor supports HTML, you can use the img HTML tag with the width and height attributes to set the dimensions of an image in pixels.

<img src="image.png" width="200" height="100">

Symbols

Markdown doesn’t provide special syntax for symbols. However, in most cases, you can copy and paste whatever symbol you want to use into your Markdown document. For example, if you need to display Pi (π), just find the symbol on a webpage and copy and paste it into your document. The symbol should appear as expected in the rendered output.

Alternatively, if your Markdown application supports HTML, you can use the HTML entity for whatever symbol you want to use. For example, if you want to display the copyright sign (©), you can copy and paste the HTML entity for copyright (©) into your Markdown document.

Here’s a partial list of HTML entities for symbols:

• Copyright (©) — ©
• Registered trademark (®) — ®
• Trademark (™) — ™
• Euro (€) — €
• Left arrow (←) — ←
• Up arrow (↑) — ↑
• Right arrow (→) — →
• Down arrow (↓) — ↓
• Degree (°) — °
• Pi (π) — π

Line Breaks Within Table Cells

You can separate paragraphs within a table cell by using one or more <br> HTML tags.

Frontmatter

Frontmatter allows you to add structured metadata to your markdown files. Add a YAML document embedded in a three-dotted block at the top of your file.

---
key: value
list:
- first
- second
object:
  nested: structure
---

# Markdown