Перейти к основному содержанию

Встроенные функции разметки

Около 5 минУчебник с примерамиVuePressРазметкаVuePress

Вот несколько улучшений, которые VuePress вносит в синтаксис Markdown.

Расширения синтаксиса

Содержимое Markdown в VuePress будет анализироваться markdown-itopen in new window, который поддерживает расширения синтаксисаopen in new window через плагины markdown-it.

В этом разделе будут представлены встроенные расширения синтаксиса Markdown для VuePress.

Вы также можете настроить эти встроенные расширения, загрузить дополнительные плагины markdown-it и реализовать свои собственные расширения с помощью опции markdownopen in new window и extendsMarkdownopen in new window.

Встроенный

Встроено в markdown-it:

Якоря заголовка

Вы могли заметить, что при наведении курсора мыши на заголовки каждого раздела отображается якорь #. Нажав якорь #, вы можете перейти непосредственно к разделу.

Совет

Это расширение привязки заголовков поддерживается markdown-it-anchoropen in new window.

Ссылка на конфигурацию: markdown.anchoropen in new window

Ссылки

При использовании Markdown синтаксис ссылкиopen in new window, VuePress реализует для вас некоторые преобразования.

В качестве примера возьмем наши исходные файлы документации:

└─ src
   ├─ cookbook
   │  └─ vuepress
   │     ├─ markdown.md <- Here we are
   │     └─ README.md
   ├─ guide
   │  └─ README.md
   ├─ contribution.md
   └─ README.md

Необработанная разметка:

<!-- relative path -->

[Главная](../../README.md)  
[Руководство по вкладу](../../contribution.md)  
[Конфиг VuePress](./config.md)

<!-- absolute path -->

[Руководство](/guide/README.md)  
[Конфиг > I18n](/config/i18n.md)

<!-- URL -->

[GitHub](https://github.com)

Конвертировано в:

<template>
  <RouterLink to="/v2/">Главная</RouterLink>
  <RouterLink to="/v2/contribution.html">Руководство по вкладу</RouterLink>
  <RouterLink to="/v2/cookbook/vuepress/config.html"
    >Конфиг VuePress</RouterLink
  >
  <RouterLink to="/v2/guide/">Руководство</RouterLink>
  <RouterLink to="/v2/config/i18n.html">Конфиг &gt; I18n</RouterLink>
  <a href="https://github.com" target="_blank" rel="noopener noreferrer"
    >GitHub</a
  >
</template>

Оформляется как:

Объяснение:

  • Внутренние ссылки будут преобразованы в <RouterLink> для навигации по SPA.
  • Внутренние ссылки на файлы .md будут преобразованы в путь маршрута страницы, поддерживаются как абсолютные, так и относительные пути.
  • Внешние ссылки получат атрибуты target="_blank" rel="noopener noreferrer".

Предложение:

Попробуйте использовать относительные пути вместо абсолютных для внутренних ссылок.

  • Относительные пути являются действительными ссылками на целевые файлы, и по ним можно правильно перемещаться при просмотре исходных файлов в вашем редакторе или репозитории.
  • Относительные пути согласованы в разных локалях, поэтому вам не нужно менять путь локали при переводе контента.
  • При использовании абсолютных путей, если baseopen in new window вашего сайта не "/", вам нужно будет добавить base вручную или используйте base хелперopen in new window.

Совет

Это расширение ссылок поддерживается нашим встроенным плагином.

Ссылка на конфигурацию: markdown.linksopen in new window

Эмодзи

Вы можете добавить смайлики в свой контент Markdown, набрав :EMOJICODE:.

Полный список доступных смайликов и кодов смотрите на emoji-cheat-sheetopen in new window.

Ввод:

VuePress 2 is out :tada: !

Вывод:

VuePress 2 is out 🎉 !

Совет

Это расширение emoji поддерживается markdown-it-emojiopen in new window.

Ссылка на конфигурацию: markdown.emojiopen in new window

Оглавление

Чтобы поместить оглавление (TOC) вашей текущей страницы в содержимое Markdown, вы можете использовать синтаксис [[toc]].

Ввод:

[[toc]]

Вывод:

Заголовки в оглавлении будут ссылаться на соответствующие привязки заголовков, поэтому оглавление не будет работать, если вы отключите привязки заголовков.

Совет

Это расширение toc поддерживается нашим встроенным плагином, который разветвлен и модифицирован из markdown-it-toc-done-rightopen in new window.

Ссылка на конфигурацию: markdown.tocopen in new window

Блоки кода

Следующие расширения блоков кода реализованы во время синтаксического анализа Markdown на стороне узла. Это означает, что блоки кода не будут обрабатываться на стороне клиента.

Подсветка линии

Вы можете выделить определенные строки ваших блоков кода, добавив метку диапазонов строк в ваши огороженные блоки кода:

Ввод:

```ts {1,6-8}
import type { UserConfig } from "vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};
```

```

```

Вывод:

import type { UserConfig } from "vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};
 




 
 
 


Примеры маркировки диапазонов строк:

  • Диапазоны строк: {5-8}
  • Несколько одиночных строк: {4,7,9}
  • Комбинированный: {4,7-13,16,23-27,40}

Совет

Это расширение для выделения строк поддерживается нашим встроенным плагином, который является разветвленным и модифицированным из markdown-it-highlight-linesopen in new window.

Ссылка на конфигурацию: markdown.code.highlightLinesopen in new window

Номера строк

Вы, должно быть, заметили, что количество строк отображается слева от блоков кода. Это включено по умолчанию, и вы можете отключить его в конфигурации.

Вы можете добавить выделение :line-numbers / :no-line-numbers в ваши изолированные блоки кода, чтобы переопределить значение, установленное в конфиге.

Ввод:

```ts
// line-numbers is enabled by default
const line2 = "This is line 2";
const line3 = "This is line 3";
```

```ts:no-line-numbers
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

Вывод:

// line-numbers is enabled by default
const line2 = "This is line 2";
const line3 = "This is line 3";

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

Совет

Это расширение номеров строк поддерживается нашим встроенным плагином.

Ссылка на конфигурацию: markdown.code.lineNumbersopen in new window

Обертка с помощью v-pre

Поскольку синтаксис шаблона разрешен в Markdown, он также будет работать в блоках кода.

Чтобы Vue не компилировал ваши блоки кода, VuePress по умолчанию добавит директиву v-preopen in new window к вашим блокам кода, что может быть отключено в конфиге.

Вы можете добавить метку :v-pre / :no-v-pre в ваши изолированные блоки кода, чтобы переопределить значение, установленное в конфиге.

Примечание

Символы синтаксиса шаблона, например синтаксис "Mustache" (двойные фигурные скобки), могут анализироваться средством подсветки синтаксиса. Таким образом, как показано в следующем примере, :no-v-pre может не работать на некоторых языках.

Чтобы синтаксис Vue все равно работал на этих языках, попробуйте отключить подсветку синтаксиса по умолчанию и реализовать собственную подсветку синтаксиса на стороне клиента.

Ввод:

```md
<!-- This will be kept as is by default -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```md:no-v-pre
<!-- This will be compiled by Vue -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```js:no-v-pre
// This won’t be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```

Вывод:

<!-- This will be kept as is -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}

<!-- This will be compiled by Vue -->
1 + 2 + 3 = 6

// This won’t be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}

Совет

Это расширение v-pre поддерживается нашим встроенным плагином.

Ссылка на конфигурацию: markdown.code.vPreopen in new window

Импорт блоков кода

Вы можете импортировать блоки кода из файлов со следующим синтаксисом:

<!-- minimal syntax -->

@[code](../foo.js)

Чтобы частично импортировать файл:

<!-- partial import, from line 1 to line 10 -->

@[code{1-10}](../foo.js)

Язык кода выводится из расширения файла, при этом рекомендуется указывать его явно:

<!-- specify the code language -->

@[code js](../foo.js)

Фактически, вторая часть внутри [] будет рассматриваться как метка ограждения кода, поэтому она поддерживает весь синтаксис, упомянутый выше в разделе Блоков кода:

<!-- line highlighting -->

@[code js{2,4-5}](../foo.js)

Вот сложный пример:

  • импортировать строку 3 в строку 10 файла "../foo.js"
  • укажите язык как "js"
  • выделить строку 3 импортированного кода, т.е. строку 5 файла "../foo.js"
  • отключить номера строк
@[code{3-10} js{3}:no-line-numbers](../foo.js)

Обратите внимание, что псевдонимы пути недоступны в синтаксисе кода импорта. Вы можете использовать следующую конфигурацию для самостоятельной обработки псевдонима пути:

import { getDirname, path } from "vuepress/utils";

const __dirname = getDirname(import.meta.url);

export default {
  markdown: {
    importCode: {
      handleImportPath: (str) =>
        str.replace(/^@src/, path.resolve(__dirname, "path/to/src")),
    },
  },
};

<!-- it will be resolved to 'path/to/src/foo.js' -->

@[code](@src/foo.js)

Совет

Это расширение кода импорта поддерживается нашим встроенным плагином.

Ссылка на конфигурацию: markdown.importCodeopen in new window

Использование Vue в Markdown

В этом разделе будут представлены некоторые основные принципы использования Vue в Markdown.

Ознакомьтесь с Учебник с примерами > Markdown и Vue SFCopen in new window для получения более подробной информации.

Синтаксис шаблона

Как мы знаем:

  • HTML разрешен в Markdown.
  • Синтаксис шаблона Vue совместим с HTML.

Это означает, что синтаксис шаблона Vueopen in new window разрешен в Markdown.

Ввод:

One plus one equals: {{ 1 + 1 }}

<span v-for="i in 3"> span: {{ i }} </span>

Вывод:

One plus one equals: 2

span: 1 span: 2 span: 3

Компоненты

Вы можете использовать компоненты Vue непосредственно в Markdown.

Ввод:

This is default theme built-in `<Badge />` component <Badge text="demo" />

Вывод:

This is default theme built-in <Badge /> component demo

Совет

Ознакомьтесь со Встроенными компонентамиopen in new window для получения полного списка встроенных компонентов.

Предостережения

Устаревшие теги HTML

Устаревшие теги HTML, такие как <center>open in new window и <font>open in new window по умолчанию не разрешены в VuePress Markdown.

Эти теги не будут распознаваться компилятором шаблонов Vue как собственные HTML-теги. Вместо этого Vue попытается разрешить эти теги как компоненты Vue, и, очевидно, эти компоненты обычно не существуют.

Вы должны стараться избегать использования устаревших тегов HTML. Однако, чтобы использовать эти теги в любом случае, попробуйте один из следующих обходных путей:

MIT Licensed | Copyright © 2019-present Mr.Hope