Pages and Styles · Docusaurus

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

Предоставляемые свойства

Docusaurus предоставляет настройки из вашего файла siteConfig.js как свойство config. Таким образом, внутри компонента React можно получить доступ к baseUrl или title через это свойство.

Пример

const React = require('react');

class MyPage extends React.Component {
  render() {
    const siteConfig = this.props.config;
    return <div>{siteConfig.title}</div>;
  }
}

module.exports = MyPage;

URL-адреса страниц

Любые файлы .js в каталоге website/pages будут трансформированы в статические файлы HTML, используя путь к файлу после pages. Файлы в каталоге website/pages/en также будут скопированы в pages и ПЕРЕЗАПИШУТ любые файлы с теми же именами в pages. Например, страницу для файла website/pages/en/help.js можно будет получить по URL-адресу ${baseUrl}en/help.js, а также по URL ${baseUrl}help.js, где ${baseUrl} это поле baseUrl, указанное в файле siteConfig.js.

Заголовки страниц

По-умолчанию, заголовок вашей страницы имеет вид <title> • <tagline>, где title и tagline - поля, указанные в siteConfig.js. Вы можете исключить слоган из заголовка, установив поле disableTitleTagline равным true. Если вы хотите указать особый заголовок для своих пользовательских страниц, добавьте свойство title в экспортируемый компонент React.

Например:

const React = require('react');

class MyPage extends React.Component {
  render() {
    // ... ваш код разметки
  }
}

MyPage.title = 'My Custom Title';

module.exports = MyPage;

Описания страниц

По-умолчанию, описание вашей страницы определено параметром tagline в siteConfig.js. Если вы хотите указать особое описание для своих пользовательских страниц, добавьте свойство description в экспортируемый компонент React.

Например:

const React = require('react');

class MyPage extends React.Component {
  render() {
    // ... ваш код разметки
  }
}

MyPage.description = 'My Custom Description';

module.exports = MyPage;

Данное свойство будет трансформировано в тег metadata description в созданном HTML.

<meta property="og:description" content="My Custom Description" />
<meta name="description" content="My Custom Description" />

Пути к подключаемым компонентам

Docusaurus предоставляет несколько полезных компонентов React для создания пользовательских страниц, найти эти компоненты можно в модуле CompLibrary. Этот модуль предоставляется как часть Docusaurus в node_modules/docusaurus, поэтому для доступа к нему, страницы из каталога pages временно копируются в node_modules/docusaurus при переработке их в статический HTML. Как видно из файлов-примеров, это означает, что пользовательская страница pages/en/index.js использует путь "../../core/CompLibrary.js" для подключения предоставленных компонентов.

Это означает, что если вы желаете использовать модуль CompLibrary, вам следует убедиться, что путь указан корректно. Например, для страницы page/mypage.js этот путь будет иметь вид "../core/CompLibrary.js".

Если вы желаете использовать свои собственные компоненты в каталоге website, используйте process.cwd(), который обращается к каталогу website для создания трубемых путей. Например, если вы добавите компонент в website/core/mycomponent.js, вы можете использовать путь "process.cwd() + /core/mycomponent.js".

Предоставляемые компоненты

Docusaurus предоставляет следующие компоненты в CompLibrary:

`CompLibrary.MarkdownBlock`

Компонент React, который анализирует разметку markdown и трансформирует её в HTML.

Например:

const MarkdownBlock = CompLibrary.MarkdownBlock;

<MarkdownBlock>
  [Синтаксис Markdown для ссылок](http://www.example.com)
</MarkdownBlock>;

`CompLibrary.Container`

Компонент-контейнер, использующий стили Docusaurus. Имеет настройки внутреннего отступа и цвета фона, которые вы можете указать.

Свойства

Свойство	Тип	По-умолчанию	Описание
`padding`	Массив, включающий значения: `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'`	`[]`	Позиции внутреннего отступа.
`background`	Одно значение из: `'dark'`, `'highlight'`, `'light'`	`null`	Стиль фона элемента.
`className`	Строка	-	Пользовательский класс css, добавляемый элементу.

Пример

<Container
  padding={['bottom', 'top']}
  background="light"
  className="myCustomClass">
  ...
</Container>

`CompLibrary.GridBlock`

Компонент React для размещения текста и изображений.

Свойства

Свойство	Тип	По-умолчанию	Описание
`align`	Одно значение из следующих: `'left'`, `'center'`, `'right'`	`'left'`	Выравнивание текста.
`layout`	Одно значение из следующих: `'twoColumn'`, `'threeColumn'`, `'fourColumn'`	`'twoColumn'`	Количество секций-колонок в `GridBlock`.
`className`	Строка	-	Пользовательский класс css, добавляемый элементу.
`contents`	Массив объектов с контентом	`[]`	Контент для каждой секции GridBlock. Обратитесь к следующей таблице за информацией о содержимом этого объекта.

Объект Content

Свойство	Тип	По-умолчанию	Описание
`title`	Строка	-	Отображаемый заголовок этого раздела, который анализируется с помощью Markdown
`content`	Строка	-	Текст этого раздела, который анализируется с помощью Markdown
`image`	Строка	-	Путь к отображаемому изображению
`imageAlt`	Строка	-	Текст, который будет показан, если изображение окажется недоступным
`imageAlign`	Одно значение из следующих: `'top'`, `'left'`, `'bottom'`, `'right'`	`'left'`	Выравнивание изображения по отношению к тексту
`imageLink`	Строка	-	Адрес, по которому произойдет переход при щелчке на изображение

Пример

<GridBlock
  align="center"
  layout="threeColumn"
  className="myCustomClass"
  contents={[
    {
      title: `[Learn](${siteConfig.baseUrl}${siteConfig.docsUrl}/tutorial.html)`,
      content: 'Learn how to use this project',
      image: siteConfig.baseUrl + 'img/learn.png',
      imageAlt: 'Learn how to use this project',
      imageLink: siteConfig.baseUrl + 'docs/tutorial.html',
    },
    {
      title: 'Frequently Asked Questions',
      content: 'Questions gathered from the community',
      image: siteConfig.baseUrl + 'img/faq.png',
      imageAlign: 'top',
    },
    {
      title: 'More',
      content: 'Lots of documentation is on this site',
    },
  ]}
/>

Дополнительные примеры использования этих компонентов можно найти среди сгенерированных файлов примеров, а также в собственном репозитории Docusaurus для настройки его веб-сайта.

Перевод строк

Когда перевод подключен, любая страница внутри каталога website/pages/en будет переведена на все подключенные языки. URL-адреса для страниц не на английском языке будут использовать языковые теги, указанные в файле languages.js. Например, URL для переведенной на французский язык страницы website/pages/en/help.js будет иметь вид ${baseUrl}fr/help.html.

Когда вы составляете страницу, которую желаете перевести, оберните каждую строку внутри нее в тег <translate>. Например:

<p>
  <translate>Мне нравится переводить</translate>
</p>

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

<a href="/community">
  <translate desc="Footer link to page referring to community GitHub and Slack">
    Community
  </translate>
</a>

Добавьте также следующее выражение require:

const translate = require('../../server/translate.js').translate;

Заметьте, что данный путен корректен для файлов внутри pages/en и должен быть скорректирован соответственно для файлов, расположенных в других местах, как обсуждалось выше.

Использование статических ресурсов

Статические ресурсы должны быть размещены в каталоге website/static. К ним можно получить доступ по их пути, из которого исключена часть static. Например, если baseUrl сайта равен /docusaurus/, то изображение website/static/img/logo.png будет доступно по адресу /docusaurus/img/logo.png.

Стили

Вам следует настроить для своего сайта цвета primary, secondary а также цвет блоков с кодом, используя поле colors в siteConfig как указано здесь. Вы также можете настроить другие цвета тем же способом, который описан в документации к siteConfig.

Есть несколько способов доступа к стилям по умолчанию, предусмотренным для вашего сайта. Если вы начали разработку вашего сайта и выполнили команду docusaurus-init или yarn install, ваши стили по умолчанию можно найти в website/node_modules/docusaurus/lib/static/css/main.css. Alternatively, the main.css file may be inspected directly at the Docusaurus GitHub repository.

Вы можете добавить собственные стили, если сохраните файл с ними в каталог website/static. Любые файлы .css, которые вы добавляете в каталог static, будут присоеденены в конец файла стилей, предоставляемого Docusaurus, что позволяет вам дополнить и/или переопределить стили Docusaurus по-умолчанию, если потребуется.

One way to figure out what classes you wish to override or add to is to start your server locally and use your browser's inspect element tool.