next

Translate

Markdown Features

Docusaurus использует GitHub Flavored Markdown (GFM). Узнайте больше об особенностях заполнения полей при создании документов Markdown для Docusaurus.

Заголовки Markdown

Документы

В документах используются следующие поля заголовка markdown, которые заключены в линии --- с обеих сторон:

  • id: Уникальный идентификатор документа. Если это поле не указано, то в качестве значения поля id будет по-умолчанию использовано наименование файла (без расширения).
  • title: Заголовок вашего документа. Если это поле не указано, в качестве значения поля title по-умолчанию будет использовано поле id.
  • hide_title: Следует ли скрыть заголовок в верхней части документа.
  • description: Описание документа, которое будет преобразовано в теги <meta name="description" content="..."/> и <meta property="og:description" content="..."/> в <head>, используемые поисковыми системами. Если это поле отсутствует, то по-умолчанию в качестве описания будет взята первая строка текста документа.
  • sidebar_label: Текст, отображаемый в боковой панелт документа и кнопках "вперед"/"назад" для этого документа. Если это поле не указано, в качестве значения поля sidebar_label по-умолчанию будет использовано поле title.

Например:

---
id: doc1
title: My Document
sidebar_label: Document
---

Версионированные документы при копировании получают изменные идентификаторы, включающие номер их версии. Новое значение поля id имеет вид version-${version}-${id}, где ${version} - номер версии документа и ${id} - исходное значение поля id. Кроме того, версионированные документы получают поле original_id, содержащие значение поля id исходного документа.

Например:

---
id: version-1.0.0-doc1
title: My Document
sidebar_label: Document
original_id: doc1
---

custom_edit_url: URL-адрес для редактирования документов. Если это поле отсутствует, будет использоваться резервный адрес editUrl указанный среди необязательных полей в siteConfig.js. Обратитесь к документации по siteConfig.js для получения дополнительной информации.

Например:

---
id: doc-markdown
title: Markdown Features
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
---

Сообщения блога

В сообщениях блога используются следующие поля заголовка markdown, которые заключены в линии --- с обеих сторон:

title: Заголовок для данного сообщения.

author: Автор данного сообщения. Если поле пропущено, имя автора не будет показано.

authorURL: Страница, на которую произойдет переход, если пользователь сайта щелкнет по имени автора. Если это поле пропущено, то имя автора не будет привязано к какой-либо странице и при щелчке перехода не будет.

authorFBID: Идентификтор Facebook автора сообщения, используется только для отображения картинки-аватара автора в сообщении. Если поле пропущено, сообщение не будет содержать аватар автора.

Например:

---
title: My First Blog Post
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---

Дополнительные возможности

Docusaurus поддерживает некоторые дополнительные возможности при составлении документации в формате markdown.

Вставка ссылок на другие документы

Вы можете использовать относительные URL-адреса на другие документы, которые будут автоматически преобразованы в гиперссылки, когда документ будет преобразован в html.

Например:

[This links to another document](other-document.md)

Эта разметка mardown будет автоматически преобразована в гиперссылку на страницу /docs/other-document.html (или в надлежащим образом переведенную/версионированную страницу), как только документ будет обработан.

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

Вставка ссылок на изображения и другие ресурсы

Статические ресурсы могут быть связаны таким же способом, что и документы, используя относительные URL. Статические ресурсы, используемые в документах и блогах, должны быть размещены в каталогах docs/assets и website/blog/assets, соответственно. Разметка markdown будет преобразована в корректные адреса для ссылок так, что эти адреса будут работать для всей документации и для всех её языков и версий.

Например:

![alt-text](assets/doc-image.png)

Создание содержания

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

Вставьте в свой файл markdown строку с текстом ``. Составьте свою документацию, используя заголовки h3 для каждой функции внутри блока с кодом. Эти ссылки будут найдены Docusaurus и список ссылок на эти разделы будут вставлены в текст <AUTOGENERATED_TABLE_OF_CONTENTS>.

Например:

### `docusaurus.function(a, b)`

Text describing my function

### `docdoc(file)`

Text describing my function

на основе этого будет создано оглавление вида:

- `docusaurus.function(a, b)`
- `docdoc(file)`

где каждая ссылка будет вести на соответствующую секцию на странице.

Вкладки с кодом для разных языков программировния

Отображайте код для различных языков программирования, используя вкладки с кодом. В первую очередь, отметьте начало и конец группы вкладок, используя <!-- DOCUSAURUS_CODE_TABS --> и <!-- END_DOCUSAURUS_CODE_TABS --> соответственно в своем markdown. Затем начните каждую вкладку с <!--[TAB_TITLE]-->.

Добавив следующий код в свой файл Markdown:

вы получите это:

console.log('Hello, world!');
print('Hello, world!')
#include <stdio.h>

int main() {
  printf("Hello World!");
  return 0;
}
program HelloWorld;
begin
  WriteLn('Hello, world!');
end.

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

Подсветка синтаксиса включена по-умолчанию для огороженных блоков кода. Язык будет определен автоматически, но в некоторых случаях вы можете добиться лучшего результата, указав язык самостоятельно. Вы можете этого добиться, используя строку информации, следующую за тремя открывающими обратными кавычками. Следующий код JavaScript...

```js
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
```

...будет преобразован с подключением подсветки синтаксиса в:

ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));

Подсветка обеспепчивается библиотекой Highlight.js, которая использует тему, указанную в файле siteConfig.js как поле объяекта highlight:

{
  ...
  highlight: {
    theme: 'default'
  }
  ...
}

Вы можете найти полный список поддерживаемых тем в Highlight.js в каталоге styles.

Регистрация дополнительных языков

В то время как Highlight.js обеспечивает поддержку многих популярных языков из коробки, вам может потребоваться добавить поддержку дополнительных языков. На этот случай мы предоставляем обходной путь для настройки, дополнив полем hljs объект highlight. This, in turn, allows you to call registerLanguage:

{
  ...
  highlight: {
    theme: 'default',
    hljs: function(hljs) {
      hljs.registerLanguage('galacticbasic', function(hljs) {
        // ...
      });
    }
  }
}

Использование Prism в качестве дополнительного инструмента подсветки синтаксиса

Вы также можете использовать Prism для подсветки определенных языков, доступных в списке здесь. Добавьте эти языки в поле usePrism в своем siteConfig.js

Например:

// siteConfig.js
usePrism: ['jsx']

Заметьте, что в блоке с кодом ниже используется подсветка синтаксиса JSX с помощью Prism.

class Example extends React.Component {
  render() {
    return (
      <View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
        <Text>Docusaurus</Text>
        <Button
          title="Click me"
          onPress={() => this.props.navigation.push('Docusaurus')}
        />
      </View>
    );
  }
}

Добавление кнопок для копирования кода

Docusaurus возволяет добавить кнопки для копирования кода из специальных блоков с кодом. Пожалуйста, следуйте инструкциям, размещенным здесь, чтобы добавить кнопки «Копировать» в ваши блоки с кодом.

← CLI CommandsPages and Styles →