siteConfig.js · Docusaurus

Большая часть настроек сайта размещена в файле siteConfig.js.

Витрина пользователей

Массив объектов users используется для хранения информации о каждом пользователе/проекте, который вы желаете показать на своем сайте. В настоящее время это поле используется в предоставляемых примерах файлов pages/en/index.js и pages/en/users.js. Каждый объект в массиве должен иметь поля caption, image, infoLink, и pinned. Текст caption отображается, когда кто-либо наводит курсор на изображение image этого пользователя, а infoLink - адрес, по которому произойдет переход при щелчке на него. Поле pinned определяет, должен ли пользователь быть отображен на странице index.

В настоящее время массив users используется только в примерах файлов index.js и users.js. Если вы не желаете иметь страницу с витриной пользователей и соответствующий раздел на странице index, вы можете удалить эту секцию.

Поля siteConfig

Объект siteConfig содержит основную часть настроек вашего веб-сайта.

Обязательные поля

`baseUrl` [string]

Базовый URL вашего сайта. Этот URL может также считаться путем после домена. Например, /metro/ - baseUrl для https://facebook.github.io/metro/. Для URL-адресов без базового пути baseUrl должен быть равен /. Это поле связано с полем url.

`colors` [object]

Описание цветовой схемы вашего сайта.

primaryColor это цвет, используемый в панели навигации в шапке сайта и боковых панелях.
secondaryColor это цвет, который можно увидеть во второй строке панели навигации в шапке страницы, когда окно браузера узкое (в том числе и на мобильных устройствах).
Также могут быть добавлены пользовательские цвета. For example, if user styles are added with colors specified as $myColor, then adding a myColor field to colors will allow you to configure this color.

`copyright` [string]

Строка копирайта в футере сайта и в пределах ленты

`favicon` [string]

URL иконки-значка favicon вашего сайта.

`headerIcon` [string]

URL иконки, используемой в навигационной панели в шапке страницы.

`headerLinks` [array]

Ссылки, которые будут использованы в навигационной панели в шапке страницы. Поле label каждого объекта будет использовано как текст ссылки и также переведено на каждый язык вашего сайта.

Пример использования:

headerLinks: [
  // Links to document with id doc1 for current language/version
  { doc: "doc1", label: "Getting Started" },
  // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
  { page: "help", label: "Help" },
  // Links to href destination, using target=_blank (external)
  { href: "https://github.com/", label: "GitHub", external: true },
  // Links to blog generated by Docusaurus (${baseUrl}blog)
  { blog: true, label: "Blog" },
  // Determines search bar position among links
  { search: true },
  // Determines language drop down position among links
  { languages: true }
],

`organizationName` [string]

Наименование учетной записи GitHub, принадлежаший организации/пользователю, предоставляющего данный проект. Эта настройка используется сценарием публикации для определения того, где на GitHub pages будет располагаться ваш веб-сайт.

`projectName` [string]

Наименование проекта. Должно соответствовать наименованию вашего GitHub репозитория (наименование регистрозависимое).

`tagline` [string]

Слоган для вашего сайта.

`title` [string]

Заголовок вашего веб-сайта.

`url` [string]

URL вашего веб-сайта. Это поле может также считаться именем домена. Например, https://facebook.github.io - это URL для https://facebook.github.io/metro/ и https://docusaurus.io - URL для https://docusaurus.io. Это поле связано с полем baseUrl.

Необязательные поля

`algolia` [object]

Настройки для интеграции с поисковой системой Algolia. Если это поле не указано, панель поиска не появится в шапке сайта. Вам следует указать два значения для этого поля, также вы можете указать одно необязательное (appId).

apiKey - API-ключ предоставленный Algolia для вашего поиска.
indexName - Algolia предоставляет имя индекса для поиска (обычно это имя проекта)
appId - Algolia по-умолчанию предоставляет скрапер для ваших документов. Если вы предоставите свой собственный, вы, вероятно, получите этот идентификатор от них.

`blogSidebarCount` [number]

Ограничение на количество сообщений вашего блога, одновременно отображаемых в боковой панели. Для получения дополнительной информации перейдите по ссылке - Добавление блогов.

`blogSidebarTitle` [string]

Заголовок боковой панели с сообщениями вашего блога. Для получения дополнительной информации перейдите по ссылке - Добавление блогов.

`cleanUrl` [boolean]

Значение true разрешает URLы без расширения HTML. Например, запрос по URL https://docusaurus.io/docs/installation вернёт тот же результат, что и https://docusaurus.io/docs/installation.html.

If users intend for this website to be used exclusively offline, this value must be set to false. Otherwise, it will cause the site to route to the parent folder of the linked page.

`cname` [string]

CNAME для вашего веб-сайта. Значение данного параметра будет скопировано в файл CNAME, когда ваш сайт будет построен.

`customDocsPath` [string]

По-умолчанию Docusaurus ожидает, что ваша документация размещена в каталоге docs. Этот каталог размещен на том же уровне, что и каталог website (т.е. не внутри каталога website). Вы можете указать свой собственный каталог для вашей документации в этом поле.

customDocsPath: 'docs/site';

customDocsPath: 'website-docs';

`defaultVersionShown` [string]

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

`deletedDocs` [object]

Even if you delete the main file for a documentation page and delete it from your sidebar, the page will still be created for every version and for the current version due to fallback functionality. This can lead to confusion if people find the documentation by searching and it appears to be something relevant to a particular version but actually is not.

To force removal of content beginning with a certain version (including for current/next), add a deletedDocs object to your config, where each key is a version and the value is an array of document IDs that should not be generated for that version and all later versions.

Например:

{
  deletedDocs: {
    "2.0.0": [
      "tagging"
    ]
  }
}

The version keys must match those in versions.json. Assuming the versions list in versions.json is ["3.0.0", "2.0.0", "1.1.0", "1.0.0"], the docs/1.0.0/tagging and docs/1.1.0/tagging URLs will work but docs/2.0.0/tagging, docs/3.0.0/tagging, and docs/tagging will not. The files and folders for those versions will not be generated during the build.

`docsUrl` [string]

Базовый URL для всех файлов документации. Установите это поле равным '' чотбы удалить префикс docs из URL документации. По-умолчанию равно docs.

`disableHeaderTitle` [boolean]

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

`disableTitleTagline` [boolean]

Настройка, отключающая отображение подзаголовка в заголовке основных страниц. Удалите это поле, чтобы сохранить заголовки страниц вида Title • Tagline. Установите его равным true, чтобы заголовки имели вид Title.

`docsSideNavCollapsible` [boolean]

Установите это значение равным true, если желаете, чтобы в боковой панели можно было раскрывать/скрывать ссылки и подкатегории.

`editUrl` [string]

URL для редактирования документов, пример использования: editUrl + 'en/doc1.md'. Если это поле не указано, документы не будут содержать кнопку "Редактировать этот документ".

`enableUpdateBy` [boolean]

Этот параметр используется для подключения отображения автора последних правок вашей документации. Установите значение параметра равным true чтобы отобразить сроку в нижнем правом углу каждого документа вида Last updated by <Author Name>.

`enableUpdateTime` [boolean]

Логическое значение, указвающее, нужно ли отображать время последнего обновления документации. Установите равным true, чтобы отобразить строку в правом нижнем углу каждого документа со следующим содержимым: Обновлено: <date>.

`facebookAppId` [string]

Если вы желаете подключить кнопки Facebook "Нравится"/"Поделиться" в футере и нижней части сообщения вашего блога, укажите идентификатор приложения Facebook.

`facebookComments` [boolean]

Установите данный параметр равным true, если желаете подключить комментарии Facebook в нижней части сообщения вашего блога. facebookAppId также должен быть указан.

`facebookPixelId` [string]

Facebook Pixel Идентификатор для отслеживания количества посещений.

`fonts` [object]

Параметр CSS font-family для сайта. Если семейство шрифтов указано в siteConfig.js как $myFont, то добавление ключа myFont в массив fonts позволит вам настроить шрифт. Элементы в начале массива имеют более высокий приоритет по сравнению с последующими элементами, так что порядок шрифтов имеет значение.

В примере ниже у нас есть два набора настроек шрифтов, myFont и myOtherFont. Times New Roman - предпочитаемый шрифт в myFont. -apple-system - предпочитаемый шрифт в myOtherFont.

fonts: {
  myFont: [
    'Times New Roman',
    'Serif'
  ],
  myOtherFont: [
    '-apple-system',
    'system-ui'
  ]
},

Шрифты выше будут представлены в ваших CSS файле(ах) как переменные $myFont и $myOtherFont.

h1 {
  font-family: $myFont;
}

`footerIcon` [string]

URL для иконки-значка в футере. В настоящее время используется в файле core/Footer.js в качестве примера и может быть удален из этого файла.

`gaTrackingId` [string]

Google Analytics идентификатор для отслеживания количества посещений.

`gaGtag` [boolean]

Установите параметр равным true, если желаете использовать глобальные теги сайта (gtag.js) для Google analytics вместо of analytics.js.

`githubHost` [string]

Hostname вашего сервера. Полезно, если вы используете GitHub Enterprise.

`highlight`

Настройки подсветки синтаксиса:

{
  // ...
  highlight: {
    // Наименование темы, используемой Highlight.js для подсветки кода.
    // Вы можете просмотреть список поддерживаемых тем здесь: 
    // https://github.com/isagalaev/highlight.js/tree/master/src/styles
    theme: 'default',

    // Конкретная версия Highlight.js, которая будет использована.
    version: '9.12.0',

    // Промежуточное звено для передачи экземпляра Highlight.js в функцию, указанную здесь, позволяет зарегистрировать дополнительные языки для подсветки.
    hljs: function(highlightJsInstance) {
      // ваш код
    },

    // Язык по-умолчанию.
    // Будет использован, если язык не указан в верхней части блока с кодом. Вы можете просмотреть список поддкрживаемых языков здесь:
    // https://github.com/isagalaev/highlight.js/tree/master/src/languages

    defaultLang: 'javascript',

    // пользовательский URL файла CSS с темой, которую вы желаете использовать в Highlight.js. Если указан, поля `theme` и `version` будут проигнорированы.
    themeUrl: 'http://foo.bar/custom.css'
  },
}

`manifest` [string]

Путь к манифесту веб-приложения (например, manifest.json). На страницу будет добавлен тег <link> в секции <head> с параметрами rel со значением "manifest" и href равным указанному пути.

`markdownOptions` [object]

Override default Remarkable options that will be used to render markdown.

To manage syntax extensions, use the markdownPlugins field.

`markdownPlugins` [array]

Массив плагинов, которые должен загрузить Remarkable - markdown анализатор и обработчик, используемый Docusaurus. Плагин получит ссылку на экземпляр Remarkable, позволяя определить пользовательские правила анализа и визуализации.

For example, if you want to enable superscript and subscript in your markdown that is rendered by Remarkable to HTML, you would do the following:

  markdownPlugins: [
    function foo(md) {
      md.inline.ruler.enable(['sub', 'sup']);
    },
  ],

`noIndex` [boolean]

Логическое значение. Если равно true, Docusaurus вежливо попросит краулеры и поисковые машины не индексировать ваш сайт. Данная настройка указывается в тэге header, в следствие этого применяется только к документам и страницам. Статические ресурсы не будут скрыты. Это наибольшее, что можно сделать. Вредоносные краулеры могут, и, вероятно, будут индексировать ваш сайт.

`ogImage` [string]

Локальный путь к изображению Open Graph (Например, img/myImage.png). Данное изображение используется, если ссылкой на ваш сайт поделились в Facebook или любых других сайтах/приложениях, поддерживающих протокол Open Graph.

`onPageNav` [string]

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

separate - Вторичная навигация - это отдельная панель с настройками по умолчанию на правой стороне документа. Пример - http://docusaurus.io/docs/en/translation.html.

`scripts` [array]

Массив сценариев JavaScript для загрузки. Значения могут быть либо строками, либо обычными объектами карт атрибута-значения. Обратитесь к примеру ниже. Тег script будет вставлен в секцию HTML head.

`separateCss` [array]

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

`scrollToTop` [boolean]

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

`scrollToTopOptions` [object]

Дополнительные настройки кнопки прокрутки страницы наверх. Данный параметр не требуется изменять, даже если вы установили scrollToTop равным true; параметр просто предоставляет вам больше настроек для кнопки. Вы можете узнать больше об этом здесь. По-умолчанию параметр zIndex равен 100.

`slugPreprocessor` [function]

Define the slug preprocessor function if you want to customize the text used for generating the hash links. Function provides the base string as the first argument and must always return a string.

`stylesheets` [array]

Массив стилей CSS для загрузки. Значения могут быть либо строками, либо обычными объектами карт атрибута-значения. Тег link будет вставлен в секцию HTML head.

`translationRecruitingLink` [string]

URL для пункта Помочь с переводом в меню выбора языка, если для документации доступны другие языки, помимо Английского. Поле может быть указано, если вы используете переводы, но это не обязательно.

`twitter` [boolean]

Установите это значение равным true, если желаете добавить кнопку социальной сети Twitter в нижней части ленты вашего блога.

`twitterUsername` [string]

Если вы желаете добавить кнопку Twitter follow в нижней части вашей страницы, укажите наименование учетной записи Twitter. Например: docusaurus.

`twitterImage` [string]

Локальный путь к изображению для карточки Twitter (например, img/myImage.png). Это изображение будет показано в карточке Twitter, когда ссылкой на ваш сайт поделятся в этой социальной сети.

`useEnglishUrl` [string]

Если вы не включили перевод текста (например, создав файл languages.js), но все еще желаете иметь ссылку вида /docs/en/doc.html (с подстрокой en), установите это поле равным true.

`users` [array]

Массив users, о котором упоминалось ранее.

`usePrism` [array]

Массив языков, используемый инструментом подсветки синтаксиса Prism. Обратитесь к руководству Использование Prism как дополнительного средства подсветки синтаксиса. Установите значение данного параметра равным true, чтобы использовать Prism для всех языков.

`wrapPagesHTML` [boolean]

Логическое значение, указывающее, должны ли HTML-файлы в /pages быть дополнены стилями, шапкой и футером сайта, сгенерированного Docusaurus. Данная функциональность является экспериментальной и предполагает, что будут использоваться файлы, содержащие HTML фрагменты вместо законченных страниц. Содержимое вашего HTML файла будет добавлено без дополнительной обработки. Значение по умолчанию: false.

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

Adding Google Fonts

Google Fonts offers faster load times by caching fonts without forcing users to sacrifice privacy. For more information on Google Fonts, see the Google Fonts documentation.

To add Google Fonts to your Docusaurus deployment, add the font path to the siteConfig.js under stylesheets:

stylesheets: [
  'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,700',
],

Пример файла siteConfig.js со множеством доступных полей

const users = [
  {
    caption: 'User1',
    image: '/test-site/img/docusaurus.svg',
    infoLink: 'https://www.example.com',
    pinned: true,
  },
];

const siteConfig = {
  title: 'Docusaurus',
  tagline: 'Generate websites!',
  url: 'https://docusaurus.io',
  baseUrl: '/',
  // For github.io type URLS, you would combine the URL and baseUrl like:
  // url: 'https://reasonml.github.io',
  // baseUrl: '/reason-react/',
  defaultVersionShown: '1.0.0',
  organizationName: 'facebook',
  projectName: 'docusaurus',
  noIndex: false,
  // For no header links in the top nav bar -> headerLinks: [],
  headerLinks: [
    {doc: 'doc1', label: 'Docs'},
    {page: 'help', label: 'Help'},
    {search: true},
    {blog: true},
  ],
  headerIcon: 'img/docusaurus.svg',
  favicon: 'img/favicon.png',
  colors: {
    primaryColor: '#2E8555',
    secondaryColor: '#205C3B',
  },
  editUrl: 'https://github.com/facebook/docusaurus/edit/master/docs/',
  // Users variable set above
  users,
  disableHeaderTitle: true,
  disableTitleTagline: true,
  separateCss: ['static/css/non-docusaurus', 'static/assets/separate-css'],
  footerIcon: 'img/docusaurus.svg',
  translationRecruitingLink: 'https://crowdin.com/project/docusaurus',
  algolia: {
    apiKey: '0f9f28b9ab9efae89810921a351753b5',
    indexName: 'github',
  },
  gaTrackingId: 'UA-12345678-9',
  highlight: {
    theme: 'default',
  },
  markdownPlugins: [
    function foo(md) {
      md.renderer.rules.fence_custom.foo = function (
        tokens,
        idx,
        options,
        env,
        instance,
      ) {
        return '<div class="foo">bar</div>';
      };
    },
  ],
  scripts: [
    'https://docusaurus.io/slash.js',
    {
      src:
        'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
  stylesheets: [
    'https://docusaurus.io/style.css',
    {
      href: 'http://css.link',
      type: 'text/css',
    },
  ],
  facebookAppId: '1615782811974223',
  facebookComments: true,
  facebookPixelId: '352490515235776',
  twitter: 'true',
  twitterUsername: 'docusaurus',
  twitterImage: 'img/docusaurus.png',
  ogImage: 'img/docusaurus.png',
  cleanUrl: true,
  scrollToTop: true,
  scrollToTopOptions: {
    zIndex: 100,
  },
  // Remove the HTML tags and HTML tags content before generating the slug
  slugPreprocessor: (slugBase) =>
    slugBase.replace(/<([^>]+?)([^>]*?)>(.*?)<\/\1>/gi, ''),
};

module.exports = siteConfig;

Витрина пользователей

Поля siteConfig

Обязательные поля

baseUrl [string]

colors [object]

copyright [string]

favicon [string]

headerIcon [string]

headerLinks [array]

organizationName [string]

projectName [string]

tagline [string]

title [string]

url [string]

Необязательные поля

algolia [object]

blogSidebarCount [number]

blogSidebarTitle [string]

cleanUrl [boolean]

cname [string]

customDocsPath [string]

defaultVersionShown [string]

deletedDocs [object]

docsUrl [string]

disableHeaderTitle [boolean]

disableTitleTagline [boolean]

docsSideNavCollapsible [boolean]

editUrl [string]

enableUpdateBy [boolean]

enableUpdateTime [boolean]

facebookAppId [string]

facebookComments [boolean]

facebookPixelId [string]

fonts [object]

footerIcon [string]

gaTrackingId [string]

gaGtag [boolean]

githubHost [string]

highlight

manifest [string]

markdownOptions [object]

markdownPlugins [array]

noIndex [boolean]

ogImage [string]

onPageNav [string]

scripts [array]

separateCss [array]

scrollToTop [boolean]

scrollToTopOptions [object]

slugPreprocessor [function]

stylesheets [array]

translationRecruitingLink [string]

twitter [boolean]

twitterUsername [string]

twitterImage [string]

useEnglishUrl [string]

users [array]

usePrism [array]

wrapPagesHTML [boolean]