Как мне сделать ссылку на маршруты, не определенные Docusaurus, из нижнего колонтитула Docusuarus? - PullRequest
Новая
       103

Как мне сделать ссылку на маршруты, не определенные Docusaurus, из нижнего колонтитула Docusuarus?

2 голосов
/ 05 августа 2020

Документация для моего веб-сайта создана с помощью Docusaurus , и в настоящее время я использую последнюю версию 2.0.0-alpha.61.

Скомпилированная документация сохраняется в /docs каталог моего веб-сайта, в то время как большая часть остальной части моего сайта построена с помощью Gatsby JS. Итак ... если вы нажмете /docs/something, вы попадете на страницу, созданную Docusaurus, но если вы нажмете /contact или /about-us или что-то еще, вы попадете на страницу, созданную с использованием Gatsby JS.

Мой docusaurus.config.js содержит: 

  baseUrl: "/docs/",
...
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: require.resolve("./sidebars/index.js"),
          showLastUpdateTime: true,
          routeBasePath: "",
        },
...

, так что Docusaurus знает, что он живет в /docs.

Вот моя проблема: в нижнем колонтитуле страниц, созданных в Docusaurus, я хотел бы ссылка на / contact или / about-us, et c., на главной странице.

Нижний колонтитул docusaurus.config.js позволяет вам иметь такие ссылки: 

{
    label: "Github",
    href: "https://github.com/my-org/my-repo",
},

или так: 

{
    label: "Contributing",
    to: "/docs/contributing",
}

Однако, если вы сделаете что-то вроде этого: 

{
    label: "About Us",
    href: "/about-us",
},

, вы получите сообщение об ошибке, указывающее, что /about-us не является допустимым URL-адресом. В сообщении об ошибке указано ValidationError: "footer.links[0].items[0].href" must be a valid uri. Предположительно это потому, что /about-us не добавляется к https://. Я бы хотел избежать определения абсолютных URL-адресов, так как я хочу иметь возможность исключить среды qa, staging и prod для веб-сайта и документации.

Если вместо этого вы сделаете что-то вроде этого: 

{
    label: "About Us",
    to: "/about-us",
},

Затем он компилируется, но маршрутизатор React Docusaurus перехватывает ссылку при нажатии, направляет вас на https://my-site.com/about-us, но показывает страницу Docusaurus 404 «не найден», поскольку маршрутизатор реакции Docusaurus не является знает о странице / о нас. Если вы обновите sh страницу, вы увидите соответствующую страницу «о нас» от Gatsby JS, поскольку маршрутизатор React Docusaurus не будет мешать, если вы попадете на страницу напрямую.

Что бы быть лучшим способом ссылки на мои страницы, созданные Gatsby JS, из нижнего колонтитула Docusaurus? Я " поменял " нижний колонтитул, и прямо сейчас у меня есть хак, где у моих ссылок docusaurus.config.js есть дополнительное свойство: 

{
    label: "About Us",
    to: "/about-us",
    localLink: true,
},

и у меня есть предложение if в моем swizzled компонент, который создает тег <a>, если localLink истинно, и создает обычный компонент ссылки React в противном случае, но я не большой поклонник swizzling компонентов с альфа-версией Docusaurus.

Есть ли лучший способ сделать ссылку на мою главную страницу из нижнего колонтитула?

Большое спасибо!

1 Ответ

0 голосов
/ 11 августа 2020

Я пытался отправить PR в Docusaurus, чтобы включить относительные ссылки в href: блоках, но это было отклонено, потому что они хотели бы, чтобы href содержали полностью определенные доменные имена в URL-адресах.

Итак, есть несколько вариантов, которые вы можете сделать, если столкнетесь с этой проблемой:

Вариант 1 : Сделайте таргетинг href: на полные URL-адреса. Для этого необходимо заранее знать, где в конечном итоге будут размещаться ваши документы. Если, например, у вас есть переменная среды MY_DOMAIN=https://my.company.com, вы можете обновить docusaurus.config.js, чтобы он читался: 

{
  label: 'About Us',
  href: process.env.MY_DOMAIN + '/about-us',
},

Обратите внимание, что если вы последуете по этому пути, вы не сможете сгенерировать свои артефакты один раз и развернуть их. в несколько сред (например, QA, staging, prod и т. д. c.). Этот URL-адрес в переменной вашей среды статически компилируется в.

Вариант 2 : используйте компоненты React <Link> с синтаксисом to:, но цель _blank: 

{
  label: 'About Us',
  to: '/about-us',
  target: '_blank' 
},

Этот вариант имеет два недостатка. Если ваш baseUrl в docusaurus.config.js не является /, это baseUrl будет добавлено к вашему целевому URL-адресу. Итак, если baseUrl='/docs/', то ссылка откроется /docs/about-us. Кроме того, ссылки открываются в новом окне. Этот вариант действительно работает для вас, только если baseUrl='/' и вас устраивает открытие ссылок в новом windows.

Вариант 3: Аккаунт для вашего baseUrl и вместо этого укажите _parent. Этот вариант аналогичен варианту 2 с двумя заметными отличиями: 

{
  label: 'About Us',
  to: '../about-us',
  target: '_parent' 
},

Во-первых, ваша to: цель учитывает ваш baseUrl, перемещая ссылку на каталог вверх. Итак, вы получите /docs/../about-us (или /about-us). Во-вторых, ваша цель _parent заставляет маршрутизатор React не фиксировать ваш клик, поэтому окно вашего браузера на самом деле меняет местоположение. Таким образом, нажатие на ссылку «О нас» фактически приводит к закрытию страницы /about-us.

Если вы выберете вариант 3, то при компиляции сайта Docusaurus вы столкнетесь с проблемой, из-за которой ваш маршрутизатор React будет заявить, что он не может разрешить /about-us (что не может, но это не имеет значения, поскольку другой сайт обрабатывает этот путь). Однако это предотвратит компиляцию вашего сайта. Чтобы игнорировать это предупреждение, добавьте 

  onBrokenLinks: "ignore",

к вашему docusaurus.config.js.

Вариант 4 : вы всегда можете поменять компонент, например NavBar или Footer, и отредактировать его по своему усмотрению, тем самым избегая проблем с проверкой docusaurus.config.js.

...