269 lines
No EOL
13 KiB
Markdown
269 lines
No EOL
13 KiB
Markdown
---
|
||
obj: format
|
||
mime: "text/markdown"
|
||
extension: "md"
|
||
wiki: https://en.wikipedia.org/wiki/Markdown
|
||
website: ["https://www.markdownguide.org", "https://commonmark.org"]
|
||
rev: 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`).
|
||
```markdown
|
||
# 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](../internet/HTML.md) 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.
|
||
```markdown
|
||
**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.
|
||
```markdown
|
||
*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.
|
||
```markdown
|
||
***All at once** text
|
||
```
|
||
|
||
### Blockquote
|
||
To create a blockquote, add a `>` in front of a paragraph.
|
||
```markdown
|
||
> 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.
|
||
```markdown
|
||
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.
|
||
```markdown
|
||
- First
|
||
- Second
|
||
- Third
|
||
```
|
||
|
||
### Code
|
||
To denote a word or phrase as code, enclose it in backticks (`` ` ``).
|
||
```markdown
|
||
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](../internet/URL.md) in parentheses (e.g., `(https://duckduckgo.com)`).
|
||
```markdown
|
||
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](../internet/URL.md) 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.
|
||
|
||
```markdown
|
||
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](../internet/URL.md) 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](../internet/HTML.md) tags in Markdown-formatted text. This is helpful if you prefer certain [HTML](../internet/HTML.md) tags to Markdown syntax. For example, some people find it easier to use [HTML](../internet/HTML.md) tags for images. Using [HTML](../internet/HTML.md) 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.
|
||
```markdown
|
||
| Syntax | Description |
|
||
| ----------- | ----------- |
|
||
| Header | Title |
|
||
| Paragraph | Text |
|
||
```
|
||
|
||
### Math
|
||
To add mathematical formulas, use LaTeX syntax enclosed within dollar symbols.
|
||
|
||
```markdown
|
||
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.
|
||
```markdown
|
||
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](../internet/CSS.md). To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.
|
||
```markdown
|
||
### My Great Heading {#custom-id}
|
||
```
|
||
|
||
The [HTML](../internet/HTML.md) looks like this:
|
||
```html
|
||
<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]`).
|
||
|
||
```markdown
|
||
- [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.
|
||
```markdown
|
||
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](../internet/HTML.md) and [CSS](../internet/CSS.md).
|
||
```html
|
||
<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](../internet/HTML.md) and [CSS](../internet/CSS.md).
|
||
```html
|
||
<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](PDF.md). 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.
|
||
|
||
```markdown
|
||
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](../internet/HTML.md), you can use the `img` [HTML](../internet/HTML.md) tag with the `width` and `height` attributes to set the dimensions of an image in pixels.
|
||
```html
|
||
<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](../internet/HTML.md), you can use the [HTML](../internet/HTML.md) 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](../internet/HTML.md) entity for copyright (`©`) into your Markdown document.
|
||
|
||
Here’s a partial list of [HTML](../internet/HTML.md) 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](../internet/HTML.md) tags.
|
||
|
||
## Frontmatter
|
||
Frontmatter allows you to add structured metadata to your markdown files. Add a [YAML](YAML.md) document embedded in a three-dotted block at the top of your file.
|
||
```markdown
|
||
---
|
||
key: value
|
||
list:
|
||
- first
|
||
- second
|
||
object:
|
||
nested: structure
|
||
---
|
||
|
||
# Markdown
|
||
``` |