Merge remote-tracking branch 'upstream/master' into subdir

crowdin.yaml

@@ -43,6 +43,10 @@ files:
         'vi': 'vi'
         'zh-CN': 'zh-CN'
         'zh-TW': 'zh-TW'
+  -
+    source: '/website/versioned_docs/**/*.md'
+    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
+    languages_mapping: *anchor
   -
     source: '/website/i18n/en.json'
     translation: '/website/i18n/%locale%.json'

docs/api-site-config.md

@@ -74,6 +74,8 @@ headerLinks: [
 
 `blogSidebarCount` - Control the number of blog posts that show up in the sidebar. See the [adding a blog docs](guides-blog.md#changing-how-many-blog-posts-show-on-sidebar) for more information.
 
+`cleanUrl` - If `true`, allow URLs with no `html` extension. Example: request to URL https://docusaurus.io/docs/installation will returns the same result as https://docusaurus.io/docs/installation.html.
+
 `cname` - The CNAME for your website. It will go into a `CNAME` file when your site it built.
 
 `customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation `*.md` files must still reside in a flat hierarchy. You cannot have your documents in nested directories**.
@@ -153,6 +155,10 @@ h1 {
 
 `separateCss` - Folders inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles.
 
+`scrollToTop` - Set this to `true` if you want to enable the scroll to top button at the bottom of your site.
+
+`scrollToTopOptions` - Optional options configuration for the scroll to top button. You do not need to use this, even if you set `scrollToTop` to `true`; it just provides you more configuration control of the button. You can find more options [here](https://github.com/vfeskov/vanilla-back-to-top/blob/v7.1.14/OPTIONS.md). By default, we set the zIndex option to 100. 
+
 `stylesheets` - Array of CSS sources to load. The link tag will be inserted in the HTML head.
 
 `translationRecruitingLink` - URL for the `Help Translate` tab of language selection when languages besides English are enabled. This can be included you are using translations but does not have to be.
@@ -246,6 +252,11 @@ const siteConfig = {
   twitterUsername: 'docusaurus',
   twitterImage: 'img/docusaurus.png',
   ogImage: 'img/docusaurus.png',
+  cleanUrl: true,
+  scrollToTop: true,
+  scrollToTopOptions: {
+    zIndex: 100
+  }
 };
 
 module.exports = siteConfig;

examples/basics/gitignore

@@ -10,4 +10,3 @@ website/build/
 website/yarn.lock
 website/node_modules
 website/i18n/*
-!website/i18n/en.json

lib/core/BlogPageLayout.js

@@ -11,6 +11,7 @@ const Container = require('./Container.js');
 const MetadataBlog = require('./MetadataBlog.js');
 const React = require('react');
 const Site = require('./Site.js');
+const utils = require('./utils.js');
 
 // used to generate entire blog pages, i.e. collection of truncated blog posts
 class BlogPageLayout extends React.Component {
@@ -45,7 +46,10 @@ class BlogPageLayout extends React.Component {
                       post={post}
                       content={post.content}
                       truncate={true}
-                      key={post.path + post.title}
+                      key={
+                        utils.getPath(post.path, this.props.config.cleanUrl) +
+                        post.title
+                      }
                       config={this.props.config}
                     />
                   );

lib/core/BlogPost.js

@@ -8,7 +8,7 @@
 const MarkdownBlock = require('./MarkdownBlock.js');
 const React = require('react');
 
-const utils = require('./utils');
+const utils = require('./utils.js');
 
 // inner blog component for the article itself, without sidebar/header/footer
 class BlogPost extends React.Component {
@@ -24,7 +24,12 @@ class BlogPost extends React.Component {
               <a
                 className="button"
                 href={
-                  this.props.config.baseUrl + 'blog/' + this.props.post.path
+                  this.props.config.baseUrl +
+                  'blog/' +
+                  utils.getPath(
+                    this.props.post.path,
+                    this.props.config.cleanUrl
+                  )
                 }>
                 Read More
               </a>
@@ -73,7 +78,12 @@ class BlogPost extends React.Component {
     const post = this.props.post;
     return (
       <h1>
-        <a href={this.props.config.baseUrl + 'blog/' + post.path}>
+        <a
+          href={
+            this.props.config.baseUrl +
+            'blog/' +
+            utils.getPath(post.path, this.props.config.cleanUrl)
+          }>
           {post.title}
         </a>
       </h1>

lib/core/BlogPostLayout.js

@@ -10,11 +10,14 @@ const BlogPost = require('./BlogPost.js');
 const BlogSidebar = require('./BlogSidebar.js');
 const Container = require('./Container.js');
 const Site = require('./Site.js');
+const OnPageNav = require('./nav/OnPageNav.js');
+const utils = require('./utils.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;
+    post.path = utils.getPath(post.path, this.props.config.cleanUrl);
 
     const fbComment = this.props.config.facebookAppId &&
       this.props.config.facebookComments && (
@@ -92,10 +95,12 @@ class BlogPostLayout extends React.Component {
   }
 
   render() {
+    let post = this.props.metadata;
+    post.path = utils.getPath(post.path, this.props.config.cleanUrl);
     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 +109,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}
@@ -123,6 +128,11 @@ class BlogPostLayout extends React.Component {
               </a>
             </div>
           </Container>
+          {this.props.config.onPageNav == 'separate' && (
+            <nav className="onPageNav">
+              <OnPageNav rawContent={this.props.children} />
+            </nav>
+          )}
         </div>
       </Site>
     );

lib/core/DocsLayout.js

@@ -17,11 +17,12 @@ const path = require('path');
 // component used to generate whole webpage for docs, including sidebar/header/footer
 class DocsLayout extends React.Component {
   getRelativeURL = (from, to) => {
+    const extension = this.props.config.cleanUrl ? '' : '.html';
     return (
       path
         .relative(from, to)
         .replace('\\', '/')
-        .replace(/^\.\.\//, '') + '.html'
+        .replace(/^\.\.\//, '') + extension
     );
   };
 

lib/core/Head.js

@@ -149,6 +149,33 @@ class Head extends React.Component {
             );
           })}
 
+        {this.props.config.scrollToTop && (
+          <script
+            src={
+              'https://unpkg.com/vanilla-back-to-top@7.1.14/dist/vanilla-back-to-top.min.js'
+            }
+          />
+        )}
+        {this.props.config.scrollToTop && (
+          <script
+            dangerouslySetInnerHTML={{
+              __html: `
+        document.addEventListener("DOMContentLoaded", function(){
+          addBackToTop(
+            ${JSON.stringify(
+              Object.assign(
+                {},
+                {zIndex: 100},
+                this.props.config.scrollToTopOptions
+              )
+            )}
+          )
+        });
+        `,
+            }}
+          />
+        )}
+
         {/* Site defined code. Keep these at the end to avoid overriding. */}
         <link
           rel="stylesheet"

lib/core/Site.js

@@ -161,6 +161,7 @@ class Site extends React.Component {
                 }}
               />
             ))}
+
           {process.env.NODE_ENV === 'development' && (
             <script
               src={`http://localhost:${

lib/core/nav/HeaderNav.js

@@ -20,6 +20,7 @@ const setLanguage = require('../../server/translate.js').setLanguage;
 const readMetadata = require('../../server/readMetadata.js');
 readMetadata.generateMetadataDocs();
 const Metadata = require('../metadata.js');
+const utils = require('../utils.js');
 
 // language dropdown nav item for when translations are enabled
 class LanguageDropDown extends React.Component {
@@ -169,22 +170,25 @@ class HeaderNav extends React.Component {
         }
         throw new Error(errorStr);
       }
-      href = this.props.config.baseUrl + Metadata[id].permalink;
+      href =
+        this.props.config.baseUrl +
+        utils.getPath(Metadata[id].permalink, this.props.config.cleanUrl);
 
       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

@@ -10,6 +10,7 @@ const classNames = require('classnames');
 
 const siteConfig = require(process.cwd() + '/siteConfig.js');
 const translation = require('../../server/translation.js');
+const utils = require('../utils.js');
 
 class SideNav extends React.Component {
   render() {
@@ -81,16 +82,22 @@ class SideNav extends React.Component {
     }
     return localizedString;
   }
+
   // return link to doc in sidebar
   getLink(metadata) {
     if (metadata.permalink) {
-      if (metadata.permalink.match(/^https?:/)) {
-        return metadata.permalink;
+      const targetLink = utils.getPath(metadata.permalink, siteConfig.cleanUrl);
+      if (targetLink.match(/^https?:/)) {
+        return targetLink;
       }
-      return siteConfig.baseUrl + metadata.permalink;
+      return siteConfig.baseUrl + targetLink;
     }
     if (metadata.path) {
-      return siteConfig.baseUrl + 'blog/' + metadata.path;
+      return (
+        siteConfig.baseUrl +
+        'blog/' +
+        utils.getPath(metadata.path, siteConfig.cleanUrl)
+      );
     }
     return null;
   }

lib/core/utils.js

@@ -20,8 +20,20 @@ function extractBlogPostSummary(content) {
   return content.substring(0, BLOG_POST_SUMMARY_LENGTH);
 }
 
+function getPath(path, cleanUrl = false) {
+  if (cleanUrl) {
+    if (path.endsWith('/index.html')) {
+      return path.replace(/\/index.html$/, '');
+    } else {
+      return path.replace(/\.html$/, '');
+    }
+  }
+  return path;
+}
+
 module.exports = {
   blogPostHasTruncateMarker,
   extractBlogPostBeforeTruncate,
   extractBlogPostSummary,
+  getPath,
 };

lib/server/generate.js

@@ -41,8 +41,14 @@ async function execute() {
   // create the folder path for a file if it does not exist, then write the file
   function writeFileAndCreateFolder(file, content) {
     mkdirp.sync(path.dirname(file));
-
     fs.writeFileSync(file, content);
+
+    // build extra file for extension-less url if "cleanUrl" siteConfig is true
+    if (siteConfig.cleanUrl && file.indexOf('index.html') === -1) {
+      const extraFile = file.replace(/\.html$/, '/index.html');
+      mkdirp.sync(path.dirname(extraFile));
+      fs.writeFileSync(extraFile, content);
+    }
   }
 
   const TABLE_OF_CONTENTS_TOKEN = '<AUTOGENERATED_TABLE_OF_CONTENTS>';
@@ -156,6 +162,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/',
@@ -196,12 +203,15 @@ async function execute() {
       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);