CODEWITHSUNDEEP
react-routerdocusaurus
Taylor Reece
Taylor Reece

Reputation: 516

How do I link to non-Docusaurus-defined routes from a Docusuarus footer?

Documentation for my website is built with Docusaurus, and I'm currently using the latest release, 2.0.0-alpha.61.

Compiled documentation is saved to the /docs directory of my website, while most of the rest of my site is built with GatsbyJS. So... if you hit /docs/something you arrive at a Docusaurus-built page, but if you hit /contact or /about-us or whatever, you hit a page built using GatsbyJS.

My docusaurus.config.js contains:

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

so that Docusaurus is aware that it lives in /docs.

Here's my issue: In the footer of pages created in Docusaurus I'd like to link to /contact or /about-us, etc., on the main page.

The footer portion of docusaurus.config.js allows you to have links like this:

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

or this:

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

However, if you do something like this:

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

You get an error noting that /about-us is not a valid url. The error states ValidationError: "footer.links[0].items[0].href" must be a valid uri. Presumably this is because /about-us isn't prepended with https://. I'd like to avoid defining absolute URLs, since I want to be able to stamp out qa, staging, and prod environments for the website and docs.

If you instead do something like this:

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

Then it compiles, but Docusaurus' React router intercepts the link when clicked, directs you to https://my-site.com/about-us, but shows a Docusaurus 404 "not found" page since Docusaurus' react router is not aware of an /about-us page. If you refresh the page you see the appropriate "about us" page from GatsbyJS, since Docusaurus' React router doesn't get in the way if you hit the page directly.

What would be the best way to link to my GatsbyJS-generated pages from the Docusaurus footer? I "swizzled" the footer and have as hack in place right now where my docusaurus.config.js links have an additional property:

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

and I have an if clause in my swizzled component that creates an <a> tag if localLink is true, and creates a normal React link component otherwise, but I'm not a huge fan of swizzling out components with an alpha release of Docusaurus.

Is there a better way to link to my main page from the footer?

Thanks a bunch!

Upvotes: 2

Views: 2447

Answers (1)

Taylor Reece
Taylor Reece

Reputation: 516

I tried to submit a PR to Docusaurus to enable relative links on href: blocks, but it was denied because they would like href's to have fully qualified domain names in the URLs.

So, there are a few options you can do if you run into this issue:

Option 1: Make your href: targets full URLs. This requires foreknowledge of where your docs will eventually live. If, for example, you have an environment variable MY_DOMAIN=https://my.company.com, you can update your docusaurus.config.js to read:

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

Note that if you follow this path, you cannot generate your artifacts once and deploy them to multiple environments (like QA, staging, prod, etc.). That URL in your environment variable is statically compiled in.

Option 2: Use React <Link> components with the to: syntax, but target _blank:

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

This option has two drawbacks. If your baseUrl in docusaurus.config.js is anything but /, that baseUrl will be prepended to your target URL. So, if baseUrl='/docs/', then the link will open /docs/about-us. Also, links open up in a new window. This option only really works for you if baseUrl='/' and you're okay with links opening in new windows.

Option 3: Account for your baseUrl, and target _parent instead. This option is similar to option 2 with two notable differences:

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

First, your to: target accounts for your baseUrl by driving your link a directory up. So, you'll end up at /docs/../about-us (or /about-us). Second, your target of _parent causes the React router to not capture your click, so your browser window actually changes location. So, clicking the "About Us" link actually results in winding up on the /about-us page.

If you choose option 3, when you compile your Docusaurus site you will run into an issue where your React router will claim it can't resolve /about-us (which it can't, but that doesn't matter since another site handles that path). It will prevent your site from compiling, though. To override that warning, add

  onBrokenLinks: "ignore",

to your docusaurus.config.js.

Option 4: You can always swizzle a component, like the NavBar or Footer, and edit it to your heart's content, thereby avoiding any docusaurus.config.js validation issues.

Upvotes: 3

Related Questions