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: [
  // Ссылки на документ с идентификатором doc1 для текущего языка/версии
  { doc: "doc1", label: "Getting Started" },
  // Ссылка на страницу pages/en/help.js или, если она не существует, на pages/help.js, для текущего языка
  { page: "help", label: "Help" },
  // Пользовательские ссылки
  { href: "https://github.com/", label: "GitHub" },
  // Ссылки на блог, созданный Docusaurus (${baseUrl}blog)
  { blog: true, label: "Blog" },
  // Определяет положение строки поиска среди ссылок
  { search: true },
  // Определяет положение переключателя языка среди ссылок
  { 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.

`cname` [string]

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

`customDocsPath` [string]

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

customDocsPath: 'docs/site';

customDocsPath: 'website-docs';

`defaultVersionShown` [string]

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

`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.

`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.

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

Пример файла 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,
  },
};

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]

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]

stylesheets [array]

translationRecruitingLink [string]

twitter [boolean]

twitterUsername [string]

twitterImage [string]

useEnglishUrl [string]

users [array]

usePrism [array]

wrapPagesHTML [boolean]