1.14.4

Translate

Navigation and Sidebars

Ссылки на документы сайта

If you want to reference another document in your docs directory (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

Например, если в документе doc2.md требуется сослаться на документ doc1.md:

Я ссылаюсь на [document](doc1.md).

Связывание документов

Новые файлы markdown внутри каталога docs будут отображаться как страницы на веб-сайте. Ссылки на эти документы создаются, в первую очередь, с помощью поля id в заголовке документа. Если поле id не указано, то для создания ссылки будет использовано имя файла.

Например, создание пустого файла с именем docs/getting-started.md приведет к появлению новой страницы с URL-адресом /docs/getting-started.html.

Предположим, что вы добавили в свой документ:

---
id: intro
title: Начало работы
---

Мой новый контент...

Если вы укажите поле id в заголовке файла markdown, доступ к документу будет осуществляться с URL-адреса в форме /docs/intro.html.

Вам нужно добавить поле id, чтобы иметь возможность добавить документ в боковую панель.

Добавление ссылок на документы в боковую панель

Много раз вам может потребоваться добавить документ в боковую панель, которая будет связана с одним из заголовков в навигационной панели в верхней части вашего веб-сайта. Наиболее распространенная боковая панель - та, что появляется при инициализации Docusaurus - боковая панель docs.

«docs» это просто название. Оно не несет никакого дополнительного смысла. Вы можете изменить его своему пожеланию.

Вы можете настроить содержимое боковой панели, а также порядок документов в ней в файле website/sidebars.json.

Пока вы не добавите свои документы в website/sidebars.json, они будут доступны только по прямому URL-адресу. Документы не будут показаны ни в одной боковой панели.

Внутри sidebars.json добавьте значение id, которое вы использовали в заголовке документа, в секцию sidebar/category. В примере ниже, docs это наименование боковой панели, а Getting Started - наименование категории внутри боковой панели.

{
  "docs": {
    "Getting Started": [
      "getting-started"
    ],
    ...
  },
  ...
}

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

{
  "docs": {
    "Моя новая категория": [
      "getting-started"
    ],
    ...
  },
  ...
}

Однако, для документа, расположенного в подкаталоге docs, как в примере ниже:

docs
└── dir1
    └── getting-started.md

Вам следует предоставить поле directory/id вместо поля id в sidebars.json.

{
  "docs": {
    "Моя новая категория": [
      "dir1/getting-started"
    ],
    ...
  },
  ...
}

Добавление подкатегорий

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

{
  "docs": {
    "My Example Category": [
      "examples",
      {
        "type": "subcategory",
        "label": "My Example Subcategory",
        "ids": [
          "my-examples",
          ...
        ]
      },
      {
        "type": "subcategory",
        "label": "My Next Subcategory",
        "ids": [
          "some-other-examples"
        ]
      },
      "even-more-examples",
      ...
    ],
    ...
  }
}

/*
В результате будет создано:

- My Example Category
  - examples
  - My Example Subcategory
    - my-examples
    ...
  - My Next Subcategory
    - some-other-examples
  - even-more-examples
  ...
*/

Добавление новых боковых панелей

Вы также можете поместить документ в новую боковую панель. В следующем примере мы создаем боковую панель examples-sidebar в файле sidebars.json, которая включает категорию My Example Category, содержащую документ с id равным my-examples.

{
  "examples-sidebar": {
    "My Example Category": [
      "my-examples"
    ],
    ...
  },
  ...
}

Важно отметить, что пока вы не добавите документ из боковой панели "examples-sidebar" на панель навигации, он будет скрыт.

Дополнения к навигационной панели сайта

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

Добавление документов

После создания новой боковой панели для сайта добавив её в sidebars.json, вы можете выставить новую боковую панель в верхнюю панель навигации, отредактировав поле headerLinks в siteConfig.js.

{
  headerLinks: [
    ...
    { doc: 'my-examples', label: 'Examples' },
    ...
  ],
  ...
}

Метка с именем Examples будет добавлена в навигационную панель сайта, при нажатии на нее в верхней части вашего сайта будет отображена панель examples-sidebar и её документ по-умолчанию - my-examples.

Добавление пользовательских страниц

Чтобы добавить пользовательские страницы в панель навигации сайта, добавьте элементы в поле headerLinks в siteConfig.js. Например, если у нас есть страница внутри website/pages/help.js, мы добавить ссылку на нее следующим образом:

{
  headerLinks: [
    ...
    { page: 'help', label: 'Help' },
    ...
  ],
  ...
}

Метка с именем Help будет добавлена в панель навигации и при нажатии на нее будет отображено содержимое страницы help.js.

Добавление внешних ссылок

Пользовательские ссылки могут быть добавлены в панель навигации с помощью следующего элемента в siteConfig.js:

{
  headerLinks: [
    ...
    { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
    ...
  ],
  ...
}

Метка с именем GitHub будет добавлена в панель навигации и при нажатии на нее будет отображено содержимое из внешней ссылки.

Чтобы открывать внешние ссылки в новых вкладках, предоставьте флаг external: true внутри конфигурации ссылки в заголовке.

Положение навигационной панели сайта

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

Поиск

Если поиск подключен на вашем сайта, панель поиска появится справа от ваших ссылок. Если вы желаете разместить её между ссылками в шапке, добавьте элемент панели в массив настроек headerLinks:

{
  headerLinks: [
    { doc: 'foo', label: 'Foo' },
    { search: true },
    { doc: 'bar', label: 'Bar' },
  ],
  ...
}

Выпадающий список языков

If translations are enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). Если вы желаете разместить его между ссылками в шапке, добавьте элемент в массив настроек headerLinks:

{
  headerLinks: [
    { doc: 'foo', label: 'Foo' },
    { languages: true },
    { doc: 'bar', label: 'Bar' },
  ],
  ...
}

Активные ссылки в навигационной панели сайта

Ссылки в верхней панели навигации получат классы siteNavItemActive и siteNavGroupActive, что позволит вам стилизовать текущую активную ссылку. siteNavItemActive применяется, когда присутствует прямое совпадение между ссылкой в панели и текущей отображаемой веб-страницей.

Данное правило не распространяется на ссылки с атрибутом href, который предназначены только для внешних ссылок. Если вручную укажите адрес href в headerLinks для внутренней страницы, документа или сообщения блога, то класс siteNavItemActive не будет применен, даже если соответствующая страница отображена.

Класс siteNavGroupActive будет добавлен к этим ссылкам:

  • doc - ссылки, которые принадлежат к той же боковой панели, что и отображаемый документ
  • The blog link when a blog post or the blog listing page is being displayed

Это два отдельных класса, так что вы можете применить стили либо только к точным совпадениям, либо немного шире - к документам, которые относятся к одной и той же группе. Если вам не нужно создавать такое различие, вы можете объединить оба класса в одном правиле CSS.

Дополнительная навигация

We support secondary on-page navigation so you can quickly see the topics associated with a given document. Чтобы включить эту функцию, вам нужно добавить поле onPageNav - параметр конфигурации сайта в свой siteConfig.js.

{
  onPageNav: 'separate',
  ...
}

В настоящее время 'separate' - единственное доступное значение для этого поля. Это обеспечивает отдельную навигацию в правой части страницы.

Раскрываемые категории

Для сайтов с большим количеством контента мы поддерживаем возможность раскрытия/скрытия ссылок и подкатегорий внутри категории. Чтобы включить эту функцию, установите поле docsSideNavCollapsible - параметр конфигурации сайта siteConfig.js равным true.

{
  docsSideNavCollapsible: true,
  ...
}
← Enabling SearchTranslations & Localization →