valaxy/docs/pages/guide/markdown.md

title_zh-CN	title	categories	end
Markdown 扩展	Markdown Extensions	guide	false

::: info 与 Hexo 不同，Valaxy 在框架层面实现了一些 Markdown 扩展（如 Container、数学公式）等，而无需主题开发者再次实现。

这与 VitePress 许多功能类似，Valaxy 从 VitePress 中借鉴了许多，并复用了 mdit-vue 的插件。 但也存在一些不同之处，此前当 Valaxy 实现数学公式时 VitePress 尚未支持，目前 Valaxy 默认的数学公式基于 KaTeX，而 VitePress 基于 MathJax。

KaTeX 相对于 MathJax 有更快的渲染速度，MathJax 则拥有更多的功能。

当然，你仍然可以在 Valaxy 中通过添加 MarkdownIt 插件来实现更多功能。 :::

Emoji 🎉

Input

:tada: :100:

Output

🎉 💯

A list of all emojis is available.

Table of Contents

Input

[[toc]]

Output

toc

Rendering of the TOC can be configured using the markdown.toc option.

代码行高亮

Input

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

Output

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

Input

```ts {1}
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers {1}
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers=2 {1}
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

Output

// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'

Colored Diffs in Code Blocks

Adding the // [!code --] or // [!code ++] comments on a line will create a diff of that line, while keeping the colors of the codeblock.

Input

Note that only one space is required after !code, here are two to prevent processing.

```js
export default {
  data () {
    return {
      msg: 'Removed' // [!code  --]
      msg: 'Added' // [!code  ++]
    }
  }
}
```

Output

export default {
  data() {
    return {
      msg: 'Removed', // [!code --]
      msg: 'Added', // [!code ++]
    }
  }
}

Errors and Warnings in Code Blocks

Adding the // [!code warning] or // [!code error] comments on a line will color it accordingly.

Input

Note that only one space is required after !code, here are two to prevent processing.

```js
export default {
  data () {
    return {
      msg: 'Error', // [!code  error]
      msg: 'Warning' // [!code  warning]
    }
  }
}
```

Output

export default {
  data() {
    return {
      msg: 'Error', // [!code error]
      msg: 'Warning' // [!code warning]
    }
  }
}

Import Code Snippets

You can import code snippets from existing files via following syntax:

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines}

Input

<<< @/snippets/snippet.js{2}

Code file

<<< @/snippets/snippet.js

Output

<<< @/snippets/snippet.js

::: tip The value of @ corresponds to the source root. By default it's the blog root, unless srcDir is configured. Alternatively, you can also import from relative paths:

<<< ../snippets/snippet.js

:::

You can also use a VS Code region to only include the corresponding part of the code file. You can provide a custom region name after a # following the filepath:

Input

<<< @/snippets/snippet-with-region.js#snippet{1}

Code file

<<< @/snippets/snippet-with-region.js

Output

<<< @/snippets/snippet-with-region.js#snippet{1}

You can also specify the language inside the braces ({}) like this:

<<< @/snippets/snippet.cs{c#}

<!-- with line highlighting: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#}

<!-- with line numbers: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}

This is helpful if source language cannot be inferred from your file extension.

Code Groups

You can group multiple code blocks like this:

Input

::: code-group

```js [config.js]
/**
 * @type {import('valaxy').UserConfig}
 */
const config = {
  // ...
}

export default config
```

```ts [config.ts]
import type { UserConfig } from 'valaxy'

const config: UserConfig = {
  // ...
}

export default config
```

:::

Output

::: code-group

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

:::

You can also import snippets in code groups:

Input

::: code-group

<!-- filename is used as title by default -->

<<< @/snippets/snippet.js

<!-- you can provide a custom one too -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

Output

::: code-group

<<< @/snippets/snippet.js

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

Container

::: zh-CN

通过对 markdownIt 进行配置，你可以自由设置自定义块区域的文字以及图标及图标的颜色。

:::

::: en

By configuring markdownIt, you can set the text and icon (and its color) for custom block.

:::

::: tip

tip

:::

::: warning

warning

:::

::: danger

danger

:::

::: info

info

:::

::: details Click to expand

details

:::

KaTeX

::: tip

More information about \KaTeX examples can be found here.

:::

Input

When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Maxwell's equations:**

| equation                                                                                                                                                                  | description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |

Output

When a \ne 0, there are two solutions to (ax^2 + bx + c = 0) and they are

 x = {-b \pm \sqrt{b^2-4ac} \over 2a} 

Maxwell's equations:

equation	description
\nabla \cdot \vec{\mathbf{B}} = 0	divergence of \vec{\mathbf{B}} is zero
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}	curl of \vec{\mathbf{E}} is proportional to the rate of change of \vec{\mathbf{B}}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho	wha?

Markdown File Inclusion

Input

# Docs

## Basics

<!--@include: ./parts/basics.md-->

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

Equivalent code

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

It also supports selecting a line range:

Input

# Docs

## Basics

<!--@include: ./parts/basics.md{3,}-->

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

Equivalent code

# Docs

## Basics

### Configuration

Can be created using `.foorc.json`.

The format of the selected line range can be: {3,}, {,10}, {1,10}

::: warning Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected. :::