feat: last updated time in docs (#913)

* Adding last updated time for docs

* Making file path general and other suggested changes

* Checking if time returned is null due to absence of git or some other issue

* Adding option to enable/disable update time feature and test-doc

* Adding simple unit tests for getGitUpdateTime()

* nits & rewrote failing test

* consistent test naming

* Adding optional updateEnableTime in documentation

* package-lock & yarn.lock

docs/api-site-config.md

@@ -98,6 +98,8 @@ customDocsPath: 'website-docs';
 
 `editUrl` - URL for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
 
+`enableUpdateTime` - An option to enable the docs showing last update time. Set to `true` to show a line at the bottom right corner of each doc page as `Last Updated: dd/mm/yyyy hh:MM:ss Z`.
+
 `facebookAppId` - If you want Facebook Like/Share buttons in the footer and at the bottom of your blog posts, provide a [Facebook application id](https://www.facebook.com/help/audiencenetwork/804209223039296).
 
 `facebookComments` - Set this to `true` if you want to enable Facebook comments at the bottom of your blog post. `facebookAppId` has to be also set.

lib/core/DocsLayout.js

@@ -16,7 +16,8 @@ const DocsSidebar = require('./DocsSidebar.js');
 const OnPageNav = require('./nav/OnPageNav.js');
 const Site = require('./Site.js');
 const translation = require('../server/translation.js');
-const {idx} = require('./utils.js');
+const docs = require('../server/docs.js');
+const {idx, getGitLastUpdated} = require('./utils.js');
 
 // component used to generate whole webpage for docs, including sidebar/header/footer
 class DocsLayout extends React.Component {
@@ -43,6 +44,12 @@ class DocsLayout extends React.Component {
     if (this.props.Doc) {
       DocComponent = this.props.Doc;
     }
+    let updateTime;
+    if (this.props.config.enableUpdateTime) {
+      const filepath = docs.getFilePath(metadata);
+      updateTime = getGitLastUpdated(filepath);
+    }
+
     const title =
       idx(i18n, ['localized-strings', 'docs', id, 'title']) || defaultTitle;
     const hasOnPageNav = this.props.config.onPageNav === 'separate';
@@ -100,6 +107,13 @@ class DocsLayout extends React.Component {
                 </a>
               )}
             </div>
+            {this.props.config.enableUpdateTime &&
+              updateTime && (
+                <p style={{fontSize: '12px', textAlign: 'right'}}>
+                  <strong>Last updated: </strong>
+                  {updateTime}
+                </p>
+              )}
           </Container>
           {hasOnPageNav && (
             <nav className="onPageNav">

lib/core/__tests__/__fixtures__/test.md

@@ -0,0 +1,5 @@
+---
+title: Don't edit this
+---
+
+Do not edit this file

lib/core/__tests__/utils.test.js

@@ -72,4 +72,29 @@ describe('utils', () => {
     expect(utils.removeExtension('/docs/test')).toBe('/docs/test');
     expect(utils.removeExtension('pages.js')).toBe('pages');
   });
+
+  test('getGitLastUpdated', () => {
+    // existing test file in repository with git timestamp
+    const existingFilePath = path.join(__dirname, '__fixtures__', 'test.md');
+    const gitLastUpdated = utils.getGitLastUpdated(existingFilePath);
+    expect(typeof gitLastUpdated).toBe('string');
+    expect(Date.parse(gitLastUpdated)).not.toBeNaN();
+    expect(gitLastUpdated).not.toBeNull();
+
+    // non existing file
+    const nonExistingFilePath = path.join(
+      __dirname,
+      '__fixtures__',
+      '.nonExisting'
+    );
+    expect(utils.getGitLastUpdated(null)).toBeNull();
+    expect(utils.getGitLastUpdated(undefined)).toBeNull();
+    expect(utils.getGitLastUpdated(nonExistingFilePath)).toBeNull();
+
+    // temporary created file that has no git timestamp
+    const tempFilePath = path.join(__dirname, '__fixtures__', '.temp');
+    fs.writeFileSync(tempFilePath, 'Lorem ipsum :)');
+    expect(utils.getGitLastUpdated(tempFilePath)).toBeNull();
+    fs.unlinkSync(tempFilePath);
+  });
 });

lib/core/utils.js

@@ -4,6 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+const spawn = require('cross-spawn');
 
 const TRUNCATE_MARKER = /<!--\s*truncate\s*-->/;
 
@@ -32,9 +33,21 @@ function idx(target, path) {
   return path.reduce((obj, key) => obj && obj[key], target);
 }
 
+function getGitLastUpdated(filepath) {
+  const timeSpan = spawn
+    .sync('git', ['log', '-1', '--format=%ct', filepath])
+    .stdout.toString('utf-8');
+  if (timeSpan) {
+    const date = new Date(parseInt(timeSpan, 10) * 1000);
+    return date.toLocaleString();
+  }
+  return null;
+}
+
 module.exports = {
   blogPostHasTruncateMarker,
   extractBlogPostBeforeTruncate,
+  getGitLastUpdated,
   getPath,
   removeExtension,
   idx,

lib/server/docs.js

@@ -15,7 +15,7 @@ const readMetadata = require('./readMetadata.js');
 const {insertTOC} = require('../core/toc.js');
 const {getPath} = require('../core/utils.js');
 
-function getFile(metadata) {
+function getFilePath(metadata) {
   if (!metadata) {
     return null;
   }
@@ -31,6 +31,14 @@ function getFile(metadata) {
   } else {
     file = join(CWD, '..', readMetadata.getDocsPath(), metadata.source);
   }
+  return file;
+}
+
+function getFile(metadata) {
+  if (!metadata) {
+    return null;
+  }
+  const file = getFilePath(metadata);
   if (!fs.existsSync(file)) {
     return null;
   }
@@ -123,6 +131,7 @@ function getRedirectMarkup(metadata) {
 module.exports = {
   getMarkup,
   getFile,
+  getFilePath,
   getRedirectMarkup,
   mdToHtmlify,
   replaceAssetsLink,

package-lock.json

@@ -2650,11 +2650,13 @@
       }
     },
     "cross-spawn": {
-      "version": "5.1.0",
+      "version": "6.0.5",
-      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-6.0.5.tgz",
-      "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=",
+      "integrity": "sha512-eTVLrBSt7fjbDygz805pMnstIs2VTBNkRm0qxZd+M7A5XDdxVRWO5MxGBXZhjY4cqLYLdtrGqRf8mBPmzwSpWQ==",
       "requires": {
-        "lru-cache": "^4.0.1",
+        "nice-try": "^1.0.4",
+        "path-key": "^2.0.1",
+        "semver": "^5.5.0",
         "shebang-command": "^1.2.0",
         "which": "^1.2.9"
       }
@@ -3094,6 +3096,11 @@
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.2.tgz",
       "integrity": "sha1-nO1l6gvAsJ9CptecGxkD+dkTzBg="
     },
+    "deepmerge": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-2.1.1.tgz",
+      "integrity": "sha512-urQxA1smbLZ2cBbXbaYObM1dJ82aJ2H57A1C/Kklfh/ZN1bgH4G/n5KWhdNfOK11W98gqZfyYj7W4frJJRwA2w=="
+    },
     "default-require-extensions": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/default-require-extensions/-/default-require-extensions-2.0.0.tgz",
@@ -3553,6 +3560,17 @@
           "integrity": "sha1-7QMXwyIGT3lGbAKWa922Bas32Zg=",
           "dev": true
         },
+        "cross-spawn": {
+          "version": "5.1.0",
+          "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz",
+          "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=",
+          "dev": true,
+          "requires": {
+            "lru-cache": "^4.0.1",
+            "shebang-command": "^1.2.0",
+            "which": "^1.2.9"
+          }
+        },
         "debug": {
           "version": "3.1.0",
           "resolved": "https://registry.npmjs.org/debug/-/debug-3.1.0.tgz",
@@ -3898,6 +3916,18 @@
         "p-finally": "^1.0.0",
         "signal-exit": "^3.0.0",
         "strip-eof": "^1.0.0"
+      },
+      "dependencies": {
+        "cross-spawn": {
+          "version": "5.1.0",
+          "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz",
+          "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=",
+          "requires": {
+            "lru-cache": "^4.0.1",
+            "shebang-command": "^1.2.0",
+            "which": "^1.2.9"
+          }
+        }
       }
     },
     "executable": {
@@ -4407,12 +4437,14 @@
         "balanced-match": {
           "version": "1.0.0",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "brace-expansion": {
           "version": "1.1.11",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "balanced-match": "^1.0.0",
             "concat-map": "0.0.1"
@@ -4427,17 +4459,20 @@
         "code-point-at": {
           "version": "1.1.0",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "concat-map": {
           "version": "0.0.1",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "console-control-strings": {
           "version": "1.1.0",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "core-util-is": {
           "version": "1.0.2",
@@ -4554,7 +4589,8 @@
         "inherits": {
           "version": "2.0.3",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "ini": {
           "version": "1.3.5",
@@ -4566,6 +4602,7 @@
           "version": "1.0.0",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "number-is-nan": "^1.0.0"
           }
@@ -4580,6 +4617,7 @@
           "version": "3.0.4",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "brace-expansion": "^1.1.7"
           }
@@ -4587,12 +4625,14 @@
         "minimist": {
           "version": "0.0.8",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "minipass": {
           "version": "2.2.4",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "safe-buffer": "^5.1.1",
             "yallist": "^3.0.0"
@@ -4611,6 +4651,7 @@
           "version": "0.5.1",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "minimist": "0.0.8"
           }
@@ -4691,7 +4732,8 @@
         "number-is-nan": {
           "version": "1.0.1",
           "bundled": true,
-          "dev": true
+          "dev": true,
+          "optional": true
         },
         "object-assign": {
           "version": "4.1.1",
@@ -4703,6 +4745,7 @@
           "version": "1.4.0",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "wrappy": "1"
           }
@@ -4824,6 +4867,7 @@
           "version": "1.0.2",
           "bundled": true,
           "dev": true,
+          "optional": true,
           "requires": {
             "code-point-at": "^1.0.0",
             "is-fullwidth-code-point": "^1.0.0",
@@ -7189,6 +7233,19 @@
             "p-finally": "^1.0.0",
             "signal-exit": "^3.0.0",
             "strip-eof": "^1.0.0"
+          },
+          "dependencies": {
+            "cross-spawn": {
+              "version": "5.1.0",
+              "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz",
+              "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=",
+              "dev": true,
+              "requires": {
+                "lru-cache": "^4.0.1",
+                "shebang-command": "^1.2.0",
+                "which": "^1.2.9"
+              }
+            }
           }
         },
         "expand-brackets": {
@@ -8299,6 +8356,11 @@
       "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.1.tgz",
       "integrity": "sha1-KzJxhOiZIQEXeyhWP7XnECrNDKk="
     },
+    "nice-try": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/nice-try/-/nice-try-1.0.5.tgz",
+      "integrity": "sha512-1nh45deeb5olNY7eX82BkPO7SSxR5SSYJiPTrTdFUVYwAl8CKMA5N9PjTYkHiRjisVcxcQ1HXdLhx2qxxJzLNQ=="
+    },
     "node-fetch": {
       "version": "1.6.3",
       "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-1.6.3.tgz",
@@ -10923,6 +10985,16 @@
             "supports-color": "^2.0.0"
           }
         },
+        "cross-spawn": {
+          "version": "5.1.0",
+          "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz",
+          "integrity": "sha1-6L0O/uWPz/b4+UUQoKVUu/ojVEk=",
+          "requires": {
+            "lru-cache": "^4.0.1",
+            "shebang-command": "^1.2.0",
+            "which": "^1.2.9"
+          }
+        },
         "figures": {
           "version": "2.0.0",
           "resolved": "https://registry.npmjs.org/figures/-/figures-2.0.0.tgz",

package.json

@@ -68,6 +68,7 @@
     "classnames": "^2.2.6",
     "color": "^2.0.1",
     "commander": "^2.16.0",
+    "cross-spawn": "^6.0.5",
     "crowdin-cli": "^0.3.0",
     "cssnano": "^3.10.0",
     "deepmerge": "^2.1.1",

website/siteConfig.js

@@ -69,6 +69,7 @@ const siteConfig = {
   scrollToTopOptions: {
     zIndex: 100,
   },
+  enableUpdateTime: true,
 };
 
 module.exports = siteConfig;

yarn.lock

@@ -1721,6 +1721,16 @@ cross-spawn@5.1.0, cross-spawn@^5.0.1, cross-spawn@^5.1.0:
     shebang-command "^1.2.0"
     which "^1.2.9"
 
+cross-spawn@^6.0.5:
+  version "6.0.5"
+  resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-6.0.5.tgz#4a5ec7c64dfae22c3a14124dbacdee846d80cbc4"
+  dependencies:
+    nice-try "^1.0.4"
+    path-key "^2.0.1"
+    semver "^5.5.0"
+    shebang-command "^1.2.0"
+    which "^1.2.9"
+
 crowdin-cli@^0.3.0:
   version "0.3.0"
   resolved "https://registry.yarnpkg.com/crowdin-cli/-/crowdin-cli-0.3.0.tgz#eac9989a6fe7feaaf33090397afc187c67b46191"
@@ -5043,6 +5053,10 @@ negotiator@0.6.1:
   version "0.6.1"
   resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.1.tgz#2b327184e8992101177b28563fb5e7102acd0ca9"
 
+nice-try@^1.0.4:
+  version "1.0.5"
+  resolved "https://registry.yarnpkg.com/nice-try/-/nice-try-1.0.5.tgz#a3378a7696ce7d223e88fc9b764bd7ef1089e366"
+
 node-fetch@1.6.3:
   version "1.6.3"
   resolved "https://registry.yarnpkg.com/node-fetch/-/node-fetch-1.6.3.tgz#dc234edd6489982d58e8f0db4f695029abcd8c04"
@@ -5482,7 +5496,7 @@ path-is-inside@^1.0.1, path-is-inside@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/path-is-inside/-/path-is-inside-1.0.2.tgz#365417dede44430d1c11af61027facf074bdfc53"
 
-path-key@^2.0.0:
+path-key@^2.0.0, path-key@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/path-key/-/path-key-2.0.1.tgz#411cadb574c5a140d3a4b1910d40d80cc9f40b40"