FutureOSS Docs

Markdown Tutorial

Mon, 20 Jan 2025 00:00:00 GMT

Markdown Tutorial

A markdown example shows how to write a markdown file. This document integrates core syntax and extensions (GMF).

Block Elements
Span Elements
- Links
- Emphasis
- Code
- Images
- Strikethrough
Miscellaneous
- Automatic Links
- Backslash Escapes
Inline HTML

Block Elements

Paragraphs and Line Breaks

Paragraphs

HTML Tag: <p>

One or more blank lines. (A blank line is a line containing nothing but spaces or tabs is considered blank.)

Code:

This will be
inline.

This is second paragraph.

Preview:

This will be inline.

This is second paragraph.

Line Breaks

HTML Tag: <br />

End a line with two or more spaces.

Code:

This will be not
inline.

Preview:

This will be not
inline.

Headers

Markdown supports two styles of headers, Setext and atx.

Setext

HTML Tags: <h1>, <h2>

“Underlined” using equal signs (=) as <h1> and dashes (-) as <h2> in any number.

Code:

This is an H1
=============
This is an H2
-------------

Preview:

This is an H1

This is an H2

atx

HTML Tags: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>

Uses 1-6 hash characters (#) at the start of the line, corresponding to <h1> - <h6>.

Code:

# This is an H1
## This is an H2
###### This is an H6

Preview:

This is an H1

This is an H2

This is an H6

Optionally, you may “close” atx-style headers. The closing hashes don’t need to match the number of hashes used to open the header.

Code:

# This is an H1 #
## This is an H2 ##
### This is an H3 ######

Preview:

This is an H1

This is an H2

This is an H3

Blockquotes

HTML Tag: <blockquote>

Markdown uses email-style > characters for blockquoting. It looks best if you hard wrap the text and put a > before every line.

Code:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Preview:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph.

Code:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

Preview:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of >.

Code:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

Preview:

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks.

Code:

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

Preview:

This is a header.

This is the first list item.

This is the second list item.

Here's some example code:
return shell_exec("echo $input | $markdown_script");

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered

HTML Tag: <ul>

Unordered lists use asterisks (*), pluses (+), and hyphens (-).

Code:

*   Red
*   Green
*   Blue

Preview:

Red
Green
Blue

is equivalent to:

Code:

+   Red
+   Green
+   Blue

and:

Code:

-   Red
-   Green
-   Blue

Ordered

HTML Tag: <ol>

Ordered lists use numbers followed by periods:

Code:

1.  Bird
2.  McHale
3.  Parish

Preview:

Bird
McHale
Parish

It’s possible to trigger an ordered list by accident, by writing something like this:

Code:

1986. What a great season.

Preview:

What a great season.

You can backslash-escape (\) the period:

Code:

1986\. What a great season.

Preview:

1986. What a great season.

Indented

Blockquote

To put a blockquote within a list item, the blockquote’s > delimiters need to be indented:

Code:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

Preview:

A list item with a blockquote:

This is a blockquote inside a list item.

Code Block

To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs:

Code:

*   A list item with a code block:

        <code goes here>

Preview:

A list item with a code block:
```
<code goes here>
```

Nested List

Code:

* A
  * A1
  * A2
* B
* C

Preview:

A
- A1
- A2
B
C

Code Blocks

HTML Tag: <pre>

Indent every line of the block by at least 4 spaces or 1 tab.

Code:

This is a normal paragraph:

    This is a code block.

Preview:

This is a normal paragraph:

This is a code block.

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities.

Code:

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

Preview:

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

Following sections Fenced Code Blocks and Syntax Highlighting are extensions, you can use the other way to write the code block.

Fenced Code Blocks

Just wrap your code in ``` (as shown below) and you won't need to indent it by four spaces.

Code:

Here's an example:

```
function test() {
  console.log("notice the blank line before this function?");
}
```

Preview:

Here's an example:

function test() {
  console.log("notice the blank line before this function?");
}

Syntax Highlighting

In your fenced block, add an optional language identifier and we'll run it through syntax highlighting (Support Languages).

Code:

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

Preview:

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

Horizontal Rules

HTML Tag: <hr /> Places three or more hyphens (-), asterisks (*), or underscores (_) on a line by themselves. You may use spaces between the hyphens or asterisks.

Code:

* * *
***
*****
- - -
---------------------------------------
___

Preview:

Table

HTML Tag: <table>

It's an extension.

Separates column by pipe (|) and header by dashes (-), and uses colon (:) for alignment.

The outer pipes (|) and alignment are optional. There are 3 delimiters each cell at least for separating header.

Code:

| Left | Center | Right |
|:-----|:------:|------:|
|aaa   |bbb     |ccc    |
|ddd   |eee     |fff    |

 A | B
---|---
123|456


A |B
--|--
12|45

Preview:

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

Span Elements

Links

HTML Tag: <a>

Markdown supports two style of links: inline and reference.

Inline

Inline link format like this: [Link Text](URL "Title")

Title is optional.

Code:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Preview:

This is an example inline link.

This link has no title attribute.

If you’re referring to a local resource on the same server, you can use relative paths:

Code:

See my [About](/about/) page for details.

Preview:

See my About page for details.

Reference

You could predefine link references. Format like this: [id]: URL "Title"

Title is also optional. And the you refer the link, format like this: [Link Text][id]

Code:

[id]: http://example.com/  "Optional Title Here"
This is [an example][id] reference-style link.

Preview:

This is an example reference-style link.

That is:

Square brackets containing the link identifier (not case sensitive, optionally indented from the left margin using up to three spaces);
followed by a colon;
followed by one or more spaces (or tabs);
followed by the URL for the link;
The link URL may, optionally, be surrounded by angle brackets.
optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

Code:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)
[foo]: <http://example.com/>  "Optional Title Here"

Uses an empty set of square brackets, the link text itself is used as the name.

Code:

[Google]: http://google.com/
[Google][]

Preview:

Google

Emphasis

HTML Tags: <em>, <strong>

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. One delimiter will be <em>; *double delimiters will be <strong>.

Code:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

Preview:

single asterisks

single underscores

double asterisks

double underscores

But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

You can backslash escape it:

Code:

\*this text is surrounded by literal asterisks\*

Preview:

*this text is surrounded by literal asterisks*

Code

HTML Tag: <code>

Wraps it with backtick quotes (`).

Code:

Use the `printf()` function.

Preview:

Use the printf() function.

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

Code:

``There is a literal backtick (`) here.``

Preview:

There is a literal backtick (`) here.

The backtick delimiters surrounding a code span may include spaces — one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

Code:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

Preview:

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

Images

HTML Tag: <img />

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline

Inline image syntax looks like this: ![Alt text](URL "Title")

Title is optional.

Code:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

Preview:

That is:

An exclamation mark: !;
followed by a set of square brackets, containing the alt attribute text for the image;
followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Reference

Reference-style image syntax looks like this: ![Alt text][id]

Code:

[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
![Alt text][img id]

Preview:

Strikethrough

HTML Tag: <del>

It's an extension.

GFM adds syntax to strikethrough text.

Code:

~~Mistaken text.~~

Preview:

~~Mistaken text.~~

Miscellaneous

Automatic Links

Markdown supports a shortcut style for creating “automatic” links for URLs and email addresses: simply surround the URL or email address with angle brackets.

Code:

<http://example.com/>

<address@example.com>

Preview:

http://example.com/

address@example.com

GFM will autolink standard URLs.

Code:

https://github.com/emn178/markdown

Preview:

https://github.com/emn178/markdown

Backslash Escapes

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax.

Code:

\*literal asterisks\*

Preview:

*literal asterisks*

Markdown provides backslash escapes for the following characters:

Code:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Inline HTML

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Code:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

Preview:

This is a regular paragraph.

This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level HTML tags.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Code:

<span>**Work**</span>

<div>
    **No Work**
</div>

Preview:

Markdown Mermaid

Sun, 01 Oct 2023 00:00:00 GMT

Complete Guide to Markdown with Mermaid Diagrams

This article demonstrates how to create various complex diagrams using Mermaid in Markdown documents, including flowcharts, sequence diagrams, Gantt charts, class diagrams, and state diagrams.

Flowchart Example

Flowcharts are excellent for representing processes or algorithm steps.

graph TD
    A[Start] --> B{Condition Check}
    B -->|Yes| C[Process Step 1]
    B -->|No| D[Process Step 2]
    C --> E[Subprocess]
    D --> E
    subgraph E [Subprocess Details]
        E1[Substep 1] --> E2[Substep 2]
        E2 --> E3[Substep 3]
    end
    E --> F{Another Decision}
    F -->|Option 1| G[Result 1]
    F -->|Option 2| H[Result 2]
    F -->|Option 3| I[Result 3]
    G --> J[End]
    H --> J
    I --> J

Sequence Diagram Example

Sequence diagrams show interactions between objects over time.

sequenceDiagram
    participant User
    participant WebApp
    participant Server
    participant Database

    User->>WebApp: Submit Login Request
    WebApp->>Server: Send Auth Request
    Server->>Database: Query User Credentials
    Database-->>Server: Return User Data
    Server-->>WebApp: Return Auth Result
    
    alt Auth Successful
        WebApp->>User: Show Welcome Page
        WebApp->>Server: Request User Data
        Server->>Database: Get User Preferences
        Database-->>Server: Return Preferences
        Server-->>WebApp: Return User Data
        WebApp->>User: Load Personalized Interface
    else Auth Failed
        WebApp->>User: Show Error Message
        WebApp->>User: Prompt Re-entry
    end

Gantt Chart Example

Gantt charts are perfect for displaying project schedules and timelines.

gantt
    title Website Development Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    
    section Design Phase
    Requirements Analysis      :a1, 2023-10-01, 7d
    UI Design                 :a2, after a1, 10d
    Prototype Creation        :a3, after a2, 5d
    
    section Development Phase
    Frontend Development      :b1, 2023-10-20, 15d
    Backend Development       :b2, after a2, 18d
    Database Design           :b3, after a1, 12d
    
    section Testing Phase
    Unit Testing              :c1, after b1, 8d
    Integration Testing       :c2, after b2, 10d
    User Acceptance Testing   :c3, after c2, 7d
    
    section Deployment
    Production Deployment     :d1, after c3, 3d
    Launch                    :milestone, after d1, 0d

Class Diagram Example

Class diagrams show the static structure of a system, including classes, attributes, methods, and their relationships.

classDiagram
    class User {
        +String username
        +String password
        +String email
        +Boolean active
        +login()
        +logout()
        +updateProfile()
    }
    
    class Article {
        +String title
        +String content
        +Date publishDate
        +Boolean published
        +publish()
        +edit()
        +delete()
    }
    
    class Comment {
        +String content
        +Date commentDate
        +addComment()
        +deleteComment()
    }
    
    class Category {
        +String name
        +String description
        +addArticle()
        +removeArticle()
    }
    
    User "1" -- "*" Article : writes
    User "1" -- "*" Comment : posts
    Article "1" -- "*" Comment : has
    Article "1" -- "*" Category : belongs to

State Diagram Example

State diagrams show the sequence of states an object goes through during its life cycle.

stateDiagram-v2
    [*] --> Draft
    
    Draft --> UnderReview : submit
    UnderReview --> Draft : reject
    UnderReview --> Approved : approve
    Approved --> Published : publish
    Published --> Archived : archive
    Published --> Draft : retract
    
    state Published {
        [*] --> Active
        Active --> Hidden : temporarily hide
        Hidden --> Active : restore
        Active --> [*]
        Hidden --> [*]
    }
    
    Archived --> [*]

Pie Chart Example

Pie charts are ideal for displaying proportions and percentage data.

pie title Website Traffic Sources Analysis
    "Search Engines" : 45.6
    "Direct Access" : 30.1
    "Social Media" : 15.3
    "Referral Links" : 6.4
    "Other Sources" : 2.6

Conclusion

Mermaid is a powerful tool for creating various types of diagrams in Markdown documents. This article demonstrated how to use flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, and pie charts. These diagrams can help you express complex concepts, processes, and data structures more clearly.

To use Mermaid, simply specify the mermaid language in a code block and describe the diagram using concise text syntax. Mermaid will automatically convert these descriptions into beautiful visual diagrams.

Try using Mermaid diagrams in your next technical blog post or project documentation - they will make your content more professional and easier to understand!

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

find wooden spoon
uncover pot
stir
cover pot
balance wooden spoon precariously on pot handle
wait 10 minutes
goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Mon, 01 Aug 2022 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili