feat: Allow modifying docs url prefix

[ghost]

siteConfig.js has a new optional field named docsUrl which default value is 'docs'.

This change will allow users who uses the library to host guides and tutorials to customize their websites by assign 'docsUrl' values like 'tutorials' or 'guides'.

Fixes #879

Motivation

See #879 - I think this is a great addition to the project.

Have you read the Contributing Guidelines on pull requests?

Yep

Test Plan

It uses the existing tests to be sure everything's working fine.

Related PRs

--

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit 59b95d7

https://deploy-preview-914--docusaurus-preview.netlify.com

[yangshun]

This is an AWESOME feature 😄

Just a small nit regarding the default route logic. @endiliey does this look good to you?

[yangshun]

Please add this to lib/core/constants instead.

[ghost]

I'll do it ASAP, thanks for the response.

[yangshun]

We're repeating this logic a few times in the code. I think we could out this in lib/server/routing.js, as a getDocsRoute function. @endiliey WYDT?

[yangshun]

Change to - Route of the documentation. By default, /docs is the default route.

[endiliey]

Sorry for the delayed response.

Please rebase and change it to docsUrl instead of docsRoute at siteConfig for consistency with v2. Will review and merge after that

[ghost]

I'll do it ASAP

[endiliey]

Clearly there is something that went wrong during rebase. I don't think +123,000 code additions is needed ...

[ghost]

Sorry, I'm kinda new to this. Can you please help me trying to figure out what went wrong?

[endiliey]

We moved v1 files to v1 folder. Since you submitted this PR way before the move, it tries to use the older folder structure.

[ghost]

Ok, so I need to redo the rebase but trying to match the folder.

[endiliey]

You should try deleting the lib or website folder that are supposed to be moved to v1 for now. As we can see there is lib/core/Metadata.js which aren't suppose to exist

[markerikson]

Pretty sure we'd like something like this for Redux / React-Redux . The existing Redux docs URLs look like https://redux.js.org/recipes/configuringyourstore , with no /docs/ prefix. We could set up redirects, but ideally I'd like to have DS generating exactly the same URLs based solely on config before we switch over.

[wgao19]

Hi here, this is a nice feature to have! Is there anything we can do to help this PR to land? 🌝

[ghost]

I'm waiting a feedback from @endiliey

[endiliey]

My bad. Seems that I'm the blocker here :|

I myself has a lot of hesitation on the PR due to v1 architecture that makes the whole implementation prone to breaks. Just look at the code and number of opaque calls like

const {getDocsUrl} = require('../../../lib/server/routing')

It's not really your fault, it just because the architecture had lot of opaque calls like require(process.cwd()/siteConfig.js

In addition, all the user will have to manually edit their url on website/pages/**.js and website/core/Footer.js since any changes we made on Docusaurus won't be ported to userland (unless it's a first install)

Furthermore, we have long implemented this in v2 and ofc the implementation is cleaner because we properly load the siteConfig (we even allow siteConfig.js live reload unlike v1) and pass it as props to whole React component of the app through React Context API.

WDYT @yangshun

[ghost]

Thanks for your feedback @endiliey, I'll look at it in-depth ASAP. I know you must be busy so thanks again for having found out time to reply.

[ghost]

Since I'm busy with school and work, I'd like if someone could look at it, too — @wgao19

[wgao19]

Hey @domcorvasce yea I'd like to help. Let me pull up a PR to your branch soon.

@endiliey, regarding your comment here:

In addition, all the user will have to manually edit their url on website/pages/**.js and website/core/Footer.js since any changes we made on Docusaurus won't be ported to userland (unless it's a first install)

We do have hardcoded docs/ in our doc site navigations now. So even if this PR lands we will have to change in our side in order to implement the customized prefix to pathname. Although I don't see a workaround? I guess the best we can do is to make sure that the changes here falls back to the hardcoded docs/ so that we don't break existing sites.

Meanwhile, may I ask when will v2 release?

[markerikson]

How's this PR looking? This is the main thing holding us back from using it for the main Redux docs site, because I'd like to have it natively generate URLs that are the same as what we have right now with Gitbook (such as https://redux.js.org/introduction/coreconcepts ).

[endiliey]

We will merge this sometimes over the weekend.

I'm trying to find some time myself to actually edit/patch the PR and test it out.

Edit:
In case this one doesnt work out, we might enable custom permalink on frontmatter to support Redux having wanted URL

Edit 2:
I find a lot of bugs when testing this out so this definitely needs a rework :|
To save everyone's else time, I will patch this PR

[markerikson]

Custom permalinks would be another viable option, sure.

[wgao19]

@endiliey Thanks so much for the work!

[JoelMarcey]

We also want to change the documentation updates in this PR to be applied to the master docs instead of version 1.3.3

[endiliey]

Alright, I managed to patch this PR and test it out in a fresh project, seems working fine so far.

One significant change that I made is that now siteConfig is being passed properly as config props to all user's own React component. Of course it's not just simple props passing, it's being processed before being passed. So if certain fields are not set, it will fill the default value.

https://github.com/facebook/Docusaurus/blob/59b95d759d736ac8957ca5db5fc029159d6cb87e/v1/lib/server/config.js#L19-L28

So now everytime user needs to access siteConfig, they don't need to do things like this (in the past)

const siteConfig = require(`${process.cwd()}/siteConfig.js`);
const docsUrl = siteConfig.docsUrl || 'docs';

At the end of the day, all user can now access the siteConfig in their React component like this

const React = require('react');

class MyPage extends React.Component {
  render() {
    const {config} = this.props;
    return <div>{config.title}</div>;
  }
}

module.exports = MyPage;

Hmm anyway,

P.S If anything breaks, we'll fix it in separate PR

Thank you @domcorvasce for starting this and @wgao19 on helping out

[markerikson]

Just used this on the React-Redux docs at https://react-redux.js.org . Thanks!

[RilDev]

Good day,

Does anyone know how to rename the /docs route on Docusaurus 2? I would like to change this url from https://my-site.com/docs/topic1/doc1 to https://my-site.com/something-else/topic1/doc1.
I looked throught the documentation and googled it to no avail.

Thank you!

[yangshun]

@RilDev Change the value of routeBasePath in the docs plugin to 'something-else'. Here's an example where I used an empty string to remove the base path but you can use any string you desire.

https://github.com/yangshun/tech-interview-handbook/blob/master/website/docusaurus.config.js#L56

@slorber indeed I couldn't find any mention of it in the docs 🤔

[RilDev]

@yangshun Thank you very much it works great!

For reference, added a routeBasePath in the presets and changed themeConfig's items's to. Here is the result:

module.exports = {
  title: 'Olivétan',
  tagline: 'La première Bible Francaise.',
  url: 'https://olivetan.fr',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'bible/', <------------------------ here
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Style Guide',
              to: 'docs/',
            },
            {
              label: 'Second Doc',
              to: 'docs/doc2/',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
            },
            {
              label: 'Discord',
              href: 'https://discordapp.com/invite/docusaurus',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/docusaurus',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'Blog',
              to: 'blog',
            },
            {
              label: 'GitHub',
              href: 'https://github.com/facebook/docusaurus',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          routeBasePath: 'bible', <------------------------ and there
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/master/website/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/master/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};