Skip to content

Latest commit

 

History

History
348 lines (248 loc) · 9.44 KB

markdown.md

File metadata and controls

348 lines (248 loc) · 9.44 KB

Markdown in VuePress: a visual guide

This section is barely even started!

Notes to yourself: using HTML comments inside Markdown

Markdown actually passes raw HTML through its preprocessor. That means you can write notes to yourself in the markdown that won't appear in the final output using HTML comments. For example, your readers will see the obviously true text All smart guitarists love the Fender Performer but they won't see the highly unreasonable Really? in the comments.

# hello, world.

All smart guitarists love the Fender Performer.

<!-- Really? -->

Code listings in Markdown files

If you're writing technical documentation you may want a way to delineate blocks of code, sometimes known as a code fence. The result is also known as a code block.

Creating a code block, aka code fence

The simplest way to show code is to wrap it between two lines consisting of 3 backticks in a row:

```
title: Welcome to Example.com
```

And the result would be:

title: Welcome to Example.com

You can get exactly the same effect by preceding each line of code with exactly 4 spaces.

Vue code inside code blocks

If you're documenting Vue.js itself, see Escaping.

Keyword highlighting

The above example is valid YAML. You could follow the 3 backticks with the word yaml to show it with keyword highlighting:

```yaml
title: Welcome to Example.com
```

The published result would show like this:

 title: Welcome to Example.com

Many, many languages are supported. Here are a few examples:

bash

Markdown source:

```bash
echo hello, world.
```

Published result:

 echo hello, world.

Javascript

Markdown source:

```js
document.write('hello, world.)
```

Published result:

  document.write('hello, world.)

Markdown

Markdown source:

 ```markdown
  ### hello, world.
 ```

Published result:

### hello, world.

Markdown (alternative)

Markdown source:

 ```md
  ### hello, world.
 ```

Published result:

### hello, world.

Python

Markdown source:

```python
print("hello, world.")
```

Published result:

print("hello, world.")

Languages with keyword highlighting support in VuePress

VuePress gets its keyword highlighting support through the Prism Javascript library.

::: tip There are too many languages to make an exhaustive list here, but you can find them in the PrismJS source file components.json. :::

Here are many of the most common ones.

Language Tag
Applecript applescript
Asciidoc asciidoc
ASP.NET aspnet
batch files batch
CSS css
Go go
HTTP http
Java java
Javascript js
JSON json
Markup markup
Markdown markdown
Markdown md
Objective-C objectivec
PHP php
Powershell powershell
Python py
Ruby ruby
SASS sass
SQL sql
Swift swift
VB.NET vbnet
Vim vim
Wiki yaml

Complete list can be found in the "languages" node of the PrismJS source file components.json.

Tables in VuePress Markdown

VuePress uses GitHub-style table markdown.

Table syntax simplified

Tables consist of a two-line required header, then zero or more rows.

  • At least one header consisting of a line surrounded by pipe characters: | Header |
  • A line of dashes surrounded by pipe characters: | ------ |
  • Zero or more rows text surrounded by pipe characters, like this: | Row 1 |

Let's put it all together.

Simple table example

To get a table that looks like this:

Header
Row 1, Column 1 Row 1, Column 2

You'd use the following markdown:

| Header                |                            |
| --------------------- | -------------------------- |
| Row 1, Column 1       | Row 1, Column 2            |

Minimum table: a header only

The absolute minimum table would consist of a single header with no rows:

Header

Markdown:

| Header                |           
| --------------------- |

Table with one header and one row:

Let's extend the previous example with one row:

Header
Single cell

Markdown:

| Header                |                            
| --------------------- | 
| Single cell           |

Typical table with several rows

Most tables have multiple columns and rows, for example:

Column 1 Column 2
Row 1, Column 1 Row 1, Column 2
Row 2, Column 1 Row 2, Column 2
Row 3, Column 1 Row 3, Column 2
Row 4, Column 1 Row 4, Column 2

Markdown:

| Column 1        | Column 2         |
| --------------- | ---------------- |
| Row 1, Column 1 | Row 1, Column 2  |
| Row 2, Column 1 | Row 2, Column 2  |
| Row 3, Column 1 | Row 3, Column 2  |
| Row 4, Column 1 | Row 4, Column 2  |

Dash and space count don't matter

The number of dashes used to specify the header and the number of spaces surrounding the pipe characters don't matter. Take the following table:

Column 1 Column 2
row 1 2nd column
row 2 2nd column

You could use this crazy-ass markdown for it:

| Column 1      | Column 2         |
| ------------ | ---------------- |
| row 1 | 2nd column  |
| row 2    | 2nd column    |

Or you could use this markup:

| Column 1     | Column 2         |
| ------------ | ---------------- |
| row 1        | 2nd column       |
| row 2        | 2nd column       |

And they would both produce the same output.

Aligning text within columns

Normally table text is left-aligned. You can change alignment by using colon characters (:) in the second header row, which contains the dash characters (-).

  • To left-align the column, replace the leftmost dash with a colon
  • To right-align the column, replace the rightmost dash with a colon
  • To center-align the column, both the leftmost and rightmost dashes with a colon

Here's a table showing alignment:

Alignment Column 2 Column 3
Center align column 2 *
Right align column 3 Boo
Right align numbers 1
123
$456.67

Markdown:

| Alignment             | Column 2       | Column 3      |
| --------------------- |:--------------:| -------------:|
| Center align column 2 | *              |               |
| Right align column 3  |                | Boo           |
| Right align numbers:  |                |   1           |
|                       |                | 123           |
|                       |                |     $456.67   |

For more details, see the GitHub style documentation.

Emojis in VuePress markdown

VuePress includes emojis as part of its Markdown extensions. You include them in your text by surrounding an emoji code with colon characters. For example, you'd use :smile: for 😄, or :thumbsup: for 👍.

Here is a table with some common emojis. For the full list of supported codes see the Emoji Cheat Sheet.

Emoji Code
😄 :smile:
😦 :frowning;
⭐ :star:
❤️ :heart:
👍 :thumbsup:
👎 :thumbsdown:
👌 :ok_hand:
✋ :hand:
❗ :exclamation:
❓ :question:
💬 :speech_balloon:
💭 :thought_balloon:
☀️ :sunny:
☁️ :cloud:
☔ :umbrella:
🌍 :earth_africa:
🔉 :sound:
🔈 :speaker:
🔇 :mute:
🔔 :bell:
🔕 :no_bell:
💻 :computer:
🔒 :lock:
🔓 :unlock:
🏠 :house:
🏢 :office:
🏥 :hospital:
🚀 :rocket:
◀️ :arrow_backward:
▶️ :arrow_forward:

Complete list: Emoji Cheat Sheet.