feat: Allow modifying docs url prefix (#914)

* Allow other routes than /docs in the URL

siteConfig.js has a new mandatory field named *docsRoute* which default
value is 'docs' and that can be customized by the user.

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

Fixes #879

* Make "docsRoute" field optional

* Isolate docsRoute login in getDocsRoute function

* Rename docsRoute to docsUrl

* Run prettier

* Remove old folders

* fix: Restore docusaurus reference link

* fix: Add `docsUrl` param fallback. Refactor multiple function calls

* Fix linting errors

* Update description for docsUrl field

* Reduce redundant calls to getDocsUrl

* Replace a missed use case for `docsUrl` instead of the function call

* Move `getDocsUrl` out from `server/routing.js` to `server/utils.js`

**Why?**
Because `routing.js` is exporting all router RegEx's, and the
`getDocsUrl` suffices more as a util

* WiP: Align leading slashes and fix routing around `docsUrl`

Checklist:
- [x] Added `removeDuplicateLeadingSlashes` util to make sure there is only
one leading slash
- [-] Fix edge cases for routing:
  - [x] `docsUrl: ''`
  - [ ] `docsUrl: '/'`
  - [ ] make it work with languages
  - [ ] make it work with versioning

* Make leading slashes canonical cross routing and generated links

This ensures correct routing for customized `baseUrl` and `docsUrl`.

- Changed all routing functions to take `siteConfig` instead of
`siteConfig.baseUrl`
- Updated tests accordingly

* Alternative fallback for `docsUrl`

* rework/ fix implementation

* cleanup

* refactor and add docs for config props

* fix typo

* fix broken url

docs/api-pages.md

@@ -5,6 +5,25 @@ title: Pages and Styles
 
 Docusaurus provides support for writing pages as React components inside the `website/pages` directory which will share the same header, footer, and styles as the rest of the site.
 
+## Provided Props
+
+Docusaurus provides your [siteConfig.js](api-site-config.md) as a `config` props. Hence, you can access `baseUrl` or `title` through this props.
+
+Example
+
+```js
+const React = require('react');
+
+class MyPage extends React.Component {
+  render() {
+    const siteConfig = this.props.config;
+    return <div>{siteConfig.title}</div>;
+  }
+}
+
+module.exports = MyPage;
+```
+
 ## URLs for Pages
 
 Any `.js` files in `website/pages` will be rendered to static HTML using the path of the file after `pages`. Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the URL `${baseUrl}en/help.js` as well as the URL `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` field set in your [siteConfig.js file](api-site-config.md).
@@ -31,7 +50,7 @@ module.exports = MyPage;
 
 ## Description for Pages
 
-By default, the description your page is `tagline` set in [`siteConfig.js`](api-site-config.md). If you want to set a specific description for your custom pages, add a `description` class property on your exported React component. 
+By default, the description your page is `tagline` set in [`siteConfig.js`](api-site-config.md). If you want to set a specific description for your custom pages, add a `description` class property on your exported React component.
 
 Example:
 
@@ -138,7 +157,7 @@ A React component to organize text and images.
   className="myCustomClass"
   contents={[
     {
-      title: `[Learn](${siteConfig.baseUrl}docs/tutorial.html)`,
+      title: `[Learn](${siteConfig.baseUrl}${siteConfig.docsUrl}/tutorial.html)`,
       content: 'Learn how to use this project',
       image: siteConfig.baseUrl + 'img/learn.png',
       imageAlt: 'Learn how to use this project',

docs/api-site-config.md

@@ -64,10 +64,6 @@ headerLinks: [
 ],
 ```
 
-#### `noIndex` [boolean]
-
-Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.
-
 #### `organizationName` [string]
 
 GitHub username of the organization or user hosting this project. This is used by the publishing script to determine where your GitHub pages website will be hosted.
@@ -130,6 +126,11 @@ customDocsPath: 'website-docs';
 
 The default version for the site to be shown. If this is not set, the latest version will be shown.
 
+#### `docsUrl` [string]
+
+The base url for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. 
+If unset, it is defaulted to `docs`.
+
 #### `disableHeaderTitle` [boolean]
 
 An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to `true`.
@@ -246,6 +247,10 @@ Path to your web app manifest (e.g., `manifest.json`). This will add a `<link>`
 
 An array of plugins to be loaded by Remarkable, the markdown parser and renderer used by Docusaurus. The plugin will receive a reference to the Remarkable instance, allowing custom parsing and rendering rules to be defined.
 
+#### `noIndex` [boolean]
+
+Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.
+
 #### `ogImage` [string]
 
 Local path to an Open Graph image (e.g., `img/myImage.png`). This image will show up when your site is shared on Facebook and other websites/apps where the Open Graph protocol is supported.

docs/guides-translation.md

@@ -65,7 +65,7 @@ You can also include an optional description attribute to give more context to a
 <p>
 ```
 
-> The `<translate>` tag generally works well on pure strings. If you have a string like "Docusaurus currently provides support to help your website use [translations](${siteConfig.baseUrl}docs/${this.props.language}/translation.html)", wrapping the `<translation>` tag around that entire string will cause issues because of the markdown linking, etc. Your options are to not translate those strings, or spread a bunch of `<translate>` tags amongst the pure substrings of that string.
+> The `<translate>` tag generally works well on pure strings. If you have a string like "Docusaurus currently provides support to help your website use [translations](${siteConfig.baseUrl}${siteConfig.docsUrl}/${this.props.language}/translation.html)", wrapping the `<translation>` tag around that entire string will cause issues because of the markdown linking, etc. Your options are to not translate those strings, or spread a bunch of `<translate>` tags amongst the pure substrings of that string.
 
 ## Gathering Strings to Translate
 

v1/examples/basics/core/Footer.js

@@ -10,7 +10,10 @@ const React = require('react');
 class Footer extends React.Component {
   docUrl(doc, language) {
     const baseUrl = this.props.config.baseUrl;
-    return `${baseUrl}docs/${language ? `${language}/` : ''}${doc}`;
+    const docsUrl = this.props.config.docsUrl;
+    const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
+    const langPart = `${language ? `${language}/` : ''}`;
+    return `${baseUrl}${docsPart}${langPart}${doc}`;
   }
 
   pageUrl(doc, language) {

v1/examples/basics/pages/en/help.js

@@ -12,47 +12,43 @@ const CompLibrary = require('../../core/CompLibrary.js');
 const Container = CompLibrary.Container;
 const GridBlock = CompLibrary.GridBlock;
 
-const siteConfig = require(`${process.cwd()}/siteConfig.js`);
-
-function docUrl(doc, language) {
-  return `${siteConfig.baseUrl}docs/${language ? `${language}/` : ''}${doc}`;
-}
-
-class Help extends React.Component {
-  render() {
-    const language = this.props.language || '';
-    const supportLinks = [
-      {
-        content: `Learn more using the [documentation on this site.](${docUrl(
-          'doc1.html',
-          language,
-        )})`,
-        title: 'Browse Docs',
-      },
-      {
-        content: 'Ask questions about the documentation and project',
-        title: 'Join the community',
-      },
-      {
-        content: "Find out what's new with this project",
-        title: 'Stay up to date',
-      },
-    ];
-
-    return (
-      <div className="docMainWrapper wrapper">
-        <Container className="mainContainer documentContainer postContainer">
-          <div className="post">
-            <header className="postHeader">
-              <h1>Need help?</h1>
-            </header>
-            <p>This project is maintained by a dedicated group of people.</p>
-            <GridBlock contents={supportLinks} layout="threeColumn" />
-          </div>
-        </Container>
-      </div>
-    );
-  }
+function Help(props) {
+  const {config: siteConfig, language = ''} = props;
+  const {baseUrl, docsUrl} = siteConfig;
+  const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
+  const langPart = `${language ? `${language}/` : ''}`;
+  const docUrl = doc => `${baseUrl}${docsPart}${langPart}${doc}`;
+
+  const supportLinks = [
+    {
+      content: `Learn more using the [documentation on this site.](${docUrl(
+        'doc1.html',
+      )})`,
+      title: 'Browse Docs',
+    },
+    {
+      content: 'Ask questions about the documentation and project',
+      title: 'Join the community',
+    },
+    {
+      content: "Find out what's new with this project",
+      title: 'Stay up to date',
+    },
+  ];
+
+  return (
+    <div className="docMainWrapper wrapper">
+      <Container className="mainContainer documentContainer postContainer">
+        <div className="post">
+          <header className="postHeader">
+            <h1>Need help?</h1>
+          </header>
+          <p>This project is maintained by a dedicated group of people.</p>
+          <GridBlock contents={supportLinks} layout="threeColumn" />
+        </div>
+      </Container>
+    </div>
+  );
 }
 
 module.exports = Help;