implement clean url routing

docs/api-site-config.md

@@ -167,6 +167,8 @@ h1 {
 
 `wrapPagesHTML` - Boolean flag to indicate whether `html` files in `/pages` should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being `html` fragments instead of complete pages. It inserts the contents of your `html` file with no extra processing. Defaults to `false`.
 
+`cleanUrl` - If `true`, request to URL https://docusaurus.io/docs/installation will returns the same result as https://docusaurus.io/docs/installation.html.
+
 Users can also add their own custom fields if they wish to provide some data across different files.
 
 ## Example siteConfig.js with many available fields

lib/core/BlogPageLayout.js

@@ -40,12 +40,20 @@ class BlogPageLayout extends React.Component {
             <div className="posts">
               {MetadataBlog.slice(page * perPage, (page + 1) * perPage).map(
                 post => {
+                  let postPath = post.path;
+                  if (this.props.config.cleanUrl) {
+                    if (postPath.endsWith('/index.html')) {
+                      postPath = postPath.replace(/\/index.html$/, '');
+                    } else {
+                      postPath = postPath.replace(/\.html$/, '');
+                    }
+                  }
                   return (
                     <BlogPost
                       post={post}
                       content={post.content}
                       truncate={true}
-                      key={post.path + post.title}
+                      key={postPath + post.title}
                       config={this.props.config}
                     />
                   );

lib/core/BlogPost.js

@@ -14,6 +14,14 @@ const utils = require('./utils');
 class BlogPost extends React.Component {
   renderContent() {
     if (this.props.truncate) {
+      let postPath = this.props.post.path;
+      if (this.props.config.cleanUrl) {
+        if (postPath.endsWith('/index.html')) {
+          postPath = postPath.replace(/\/index.html$/, '');
+        } else {
+          postPath = postPath.replace(/\.html$/, '');
+        }
+      }
       return (
         <article className="post-content">
           <MarkdownBlock>
@@ -23,9 +31,7 @@ class BlogPost extends React.Component {
             <div className="read-more">
               <a
                 className="button"
-                href={
-                  this.props.config.baseUrl + 'blog/' + this.props.post.path
-                }>
+                href={this.props.config.baseUrl + 'blog/' + postPath}>
                 Read More
               </a>
             </div>
@@ -71,9 +77,17 @@ class BlogPost extends React.Component {
 
   renderTitle() {
     const post = this.props.post;
+    let postPath = this.props.post.path;
+    if (this.props.config.cleanUrl) {
+      if (postPath.endsWith('/index.html')) {
+        postPath = postPath.replace(/\/index.html$/, '');
+      } else {
+        postPath = postPath.replace(/\.html$/, '');
+      }
+    }
     return (
       <h1>
-        <a href={this.props.config.baseUrl + 'blog/' + post.path}>
+        <a href={this.props.config.baseUrl + 'blog/' + postPath}>
           {post.title}
         </a>
       </h1>

lib/core/BlogPostLayout.js

@@ -14,7 +14,14 @@ const Site = require('./Site.js');
 // used for entire blog posts, i.e., each written blog article with sidebar with site header/footer
 class BlogPostLayout extends React.Component {
   renderSocialButtons() {
-    const post = this.props.metadata;
+    let post = this.props.metadata;
+    if (this.props.config.cleanUrl) {
+      if (post.path.endsWith('/index.html')) {
+        post.path = post.path.replace(/\/index.html$/, '');
+      } else {
+        post.path = post.path.replace(/\.html$/, '');
+      }
+    }
 
     const fbComment = this.props.config.facebookAppId &&
       this.props.config.facebookComments && (
@@ -92,10 +99,18 @@ class BlogPostLayout extends React.Component {
   }
 
   render() {
+    let post = this.props.metadata;
+    if (this.props.config.cleanUrl) {
+      if (post.path.endsWith('/index.html')) {
+        post.path = post.path.replace(/\/index.html$/, '');
+      } else {
+        post.path = post.path.replace(/\.html$/, '');
+      }
+    }
     return (
       <Site
         className="sideNavVisible"
-        url={'blog/' + this.props.metadata.path}
+        url={'blog/' + post.path}
         title={this.props.metadata.title}
         language={'en'}
         description={this.getDescription()}
@@ -104,13 +119,13 @@ class BlogPostLayout extends React.Component {
         <div className="docMainWrapper wrapper">
           <BlogSidebar
             language={'en'}
-            current={this.props.metadata}
+            current={post}
             config={this.props.config}
           />
           <Container className="mainContainer documentContainer postContainer blogContainer">
             <div className="lonePost">
               <BlogPost
-                post={this.props.metadata}
+                post={post}
                 content={this.props.children}
                 language={'en'}
                 config={this.props.config}

lib/core/nav/HeaderNav.js

@@ -169,22 +169,31 @@ class HeaderNav extends React.Component {
         }
         throw new Error(errorStr);
       }
-      href = this.props.config.baseUrl + Metadata[id].permalink;
+      let metadataLink = Metadata[id].permalink;
+      if (siteConfig.cleanUrl) {
+        if (metadataLink.endsWith('/index.html')) {
+          metadataLink = metadataLink.replace(/\/index.html$/, '');
+        } else {
+          metadataLink = metadataLink.replace(/\.html$/, '');
+        }
+      }
+      href = this.props.config.baseUrl + metadataLink;
 
       const {id: currentID, sidebar} = this.props.current;
       docItemActive = currentID && currentID === id;
       docGroupActive = sidebar && sidebar === Metadata[id].sidebar;
     } else if (link.page) {
       // set link to page with current page's language if appropriate
       const language = this.props.language || '';
+      const extension = siteConfig.cleanUrl ? '' : '.html';
       if (fs.existsSync(CWD + '/pages/en/' + link.page + '.js')) {
         href =
           siteConfig.baseUrl +
           (language ? language + '/' : '') +
           link.page +
-          '.html';
+          extension;
       } else {
-        href = siteConfig.baseUrl + link.page + '.html';
+        href = siteConfig.baseUrl + link.page + extension;
       }
     } else if (link.href) {
       // set link to specified href

lib/core/nav/SideNav.js

@@ -84,13 +84,30 @@ class SideNav extends React.Component {
   // return link to doc in sidebar
   getLink(metadata) {
     if (metadata.permalink) {
-      if (metadata.permalink.match(/^https?:/)) {
-        return metadata.permalink;
+      let targetLink = metadata.permalink;
+      if (siteConfig.cleanUrl) {
+        if (targetLink.endsWith('/index.html')) {
+          targetLink = targetLink.replace(/\/index.html$/, '');
+        } else {
+          targetLink = targetLink.replace(/\.html$/, '');
+        }
       }
-      return siteConfig.baseUrl + metadata.permalink;
+
+      if (targetLink.match(/^https?:/)) {
+        return targetLink;
+      }
+      return siteConfig.baseUrl + targetLink;
     }
     if (metadata.path) {
-      return siteConfig.baseUrl + 'blog/' + metadata.path;
+      let targetPath = metadata.path;
+      if (siteConfig.cleanUrl) {
+        if (targetPath.endsWith('/index.html')) {
+          targetPath = targetPath.replace(/\/index.html$/, '');
+        } else {
+          targetPath = targetPath.replace(/\.html$/, '');
+        }
+      }
+      return siteConfig.baseUrl + 'blog/' + targetPath;
     }
     return null;
   }

lib/server/generate.js

@@ -156,6 +156,7 @@ async function execute() {
     // replace any links to markdown files to their website html links
     Object.keys(mdToHtml).forEach(function(key, index) {
       let link = mdToHtml[key];
+      link = siteConfig.cleanUrl ? link.replace(/\.html$/, '') : link;
       link = link.replace('/en/', '/' + language + '/');
       link = link.replace(
         '/VERSION/',
@@ -191,17 +192,28 @@ async function execute() {
     const targetFile = join(buildDir, metadata.permalink);
     writeFileAndCreateFolder(targetFile, str);
 
+    // build extra files for extension-less url
+    if (siteConfig.cleanUrl) {
+      writeFileAndCreateFolder(
+        targetFile.replace(/\.html$/, '/index.html'),
+        str
+      );
+    }
+
     // generate english page redirects when languages are enabled
     if (
       env.translation.enabled &&
       metadata.permalink.indexOf('docs/en') !== -1
     ) {
+      const redirectlink = siteConfig.cleanUrl
+        ? metadata.permalink.replace(/\.html$/, '')
+        : metadata.permalink;
       const redirectComp = (
         <Redirect
           metadata={metadata}
           language={language}
           config={siteConfig}
-          redirect={siteConfig.baseUrl + metadata.permalink}
+          redirect={siteConfig.baseUrl + redirectlink}
         />
       );
       const redirectStr = renderToStaticMarkupWithDoctype(redirectComp);
@@ -212,6 +224,14 @@ async function execute() {
         metadata.permalink.replace('docs/en', 'docs')
       );
       writeFileAndCreateFolder(redirectFile, redirectStr);
+
+      // build extra files for extension-less url
+      if (siteConfig.cleanUrl) {
+        writeFileAndCreateFolder(
+          redirectFile.replace(/\.html$/, '/index.html'),
+          redirectStr
+        );
+      }
     }
   });
 
@@ -274,6 +294,12 @@ async function execute() {
 
       let targetFile = join(buildDir, 'blog', filePath);
       writeFileAndCreateFolder(targetFile, str);
+
+      // build extra files for extension-less url
+      if (siteConfig.cleanUrl) {
+        let cleanTargetFile = targetFile.replace(/\.html$/, '/index.html');
+        writeFileAndCreateFolder(cleanTargetFile, str);
+      }
     });
   // create html files for all blog pages (collections of article previews)
   const BlogPageLayout = require('../core/BlogPageLayout.js');
@@ -507,6 +533,15 @@ async function execute() {
             targetFile.replace(sep + 'en' + sep, sep + language + sep),
             str
           );
+          // build extra files for extension-less url
+          if (siteConfig.cleanUrl && targetFile.indexOf('index.html') < 0) {
+            writeFileAndCreateFolder(
+              targetFile
+                .replace(sep + 'en' + sep, sep + language + sep)
+                .replace(/\.html$/, '/index.html'),
+              str
+            );
+          }
         }
 
         // write to base level
@@ -521,6 +556,16 @@ async function execute() {
           targetFile.replace(sep + 'en' + sep, sep),
           str
         );
+
+        // build extra files for extension-less url
+        if (siteConfig.cleanUrl && targetFile.indexOf('index.html') < 0) {
+          writeFileAndCreateFolder(
+            targetFile
+              .replace(sep + 'en' + sep, sep)
+              .replace(/\.html$/, '/index.html'),
+            str
+          );
+        }
       } else {
         // allow for rendering of other files not in pages/en folder
         let language = env.translation.enabled ? 'en' : '';
@@ -534,6 +579,16 @@ async function execute() {
           targetFile.replace(sep + 'en' + sep, sep),
           str
         );
+
+        // build extra files for extension-less url
+        if (siteConfig.cleanUrl && targetFile.indexOf('index.html') < 0) {
+          writeFileAndCreateFolder(
+            targetFile
+              .replace(sep + 'en' + sep, sep)
+              .replace(/\.html$/, '/index.html'),
+            str
+          );
+        }
       }
       fs.removeSync(tempFile);
     } else if (siteConfig.wrapPagesHTML && normalizedFile.match(/\.html$/)) {