Markdown Extensions
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::tada: :100:Output
🎉 💯
A list of all emojis is available.
Table of Contents
Input
[[toc]][[toc]]Output
Rendering of the TOC can be configured using the markdown.toc option.
代码行高亮
Input
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
``````js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```Output
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}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'
``````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 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
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'// 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 ++]
}
}
}
``````js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```Output
export default {
data() {
return {
msg: 'Removed',
msg: 'Added',
}
}
}export default {
data() {
return {
msg: 'Removed',
msg: 'Added',
}
}
}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]
}
}
}
``````js
export default {
data () {
return {
msg: 'Error', // [!code error]
msg: 'Warning' // [!code warning]
}
}
}
```Output
export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}Import Code Snippets
You can import code snippets from existing files via following syntax:
<<< @/filepath<<< @/filepathIt also supports line highlighting:
<<< @/filepath{highlightLines}<<< @/filepath{highlightLines}Input
<<< @/snippets/snippet.js{2}<<< @/snippets/snippet.js{2}Code file
export default function () {
// ..
}export default function () {
// ..
}Output
export default function () {
// ..
}export default function () {
// ..
}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<<< ../snippets/snippet.jsYou 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}<<< @/snippets/snippet-with-region.js#snippet{1}Code file
// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default foo// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default fooOutput
function foo() {
// ..
}function foo() {
// ..
}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}<<< @/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
```
:::::: 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
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default configimport type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default configimport type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default configYou 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]
:::::: 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
export default function () {
// ..
}export default function () {
// ..
}function foo() {
// ..
}function foo() {
// ..
}Container
通过对 markdownIt 进行配置，你可以自由设置自定义块区域的文字以及图标及图标的颜色。
By configuring markdownIt, you can set the text and icon (and its color) for custom block.
TIP提示
tip
WARNING注意
warning
DANGER警告
danger
INFO信息
info
Click to expand
details
KaTeX
TIP提示
More information about 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?_ |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 , there are two solutions to and they are
Maxwell's equations:
| equation | description |
|---|---|
| divergence of is zero | |
| curl of is proportional to the rate of change of | |
| wha? |
Markdown File Inclusion
TIP提示
You can also prefix the markdown path with @, it will act as the source root. By default, it's the Valaxy project root.
Input
## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md-->## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md-->Part file
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.I'm a TEST.I'm a TEST.Equivalent code
## Docs
I'm a TEST.
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.## Docs
I'm a TEST.
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.It also supports selecting a line range:
Input
## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md{3,}-->## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md{3,}-->Part file
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.I'm a TEST.I'm a TEST.Equivalent code
## Docs
I'm a TEST.
### Configuration
Can be created using `.foorc.json`.## Docs
I'm a TEST.
### 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.
To Be Continued.