refactor(v2): enhance CLI experience

admin/extending-remarkable.md

@@ -53,11 +53,11 @@ Now that you have a better idea of how parsing/rendering works, we can proceed t
 The default heading renderers may look like this (you can refer to the Remarkable source code here):
 
 ```js
-md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
+md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
   return '<h' + tokens[idx].hLevel + '>';
 };
 
-md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) {
+md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
   return '</h' + tokens[idx].hLevel + '>\n';
 };
 ```
@@ -74,7 +74,7 @@ That's pretty straightforward: whenever these tokens are found, we render a `<hN
 In that case, we need to override our heading rules like so:
 
 ```js
-md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
+md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
   return (
     '<h' +
     tokens[idx].hLevel +
@@ -85,7 +85,7 @@ md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
   );
 };
 
-md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) {
+md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
   return (
     ' <a class="hash-link" href="#' +
     toSlug(tokens[idx - 1].content) +
@@ -105,7 +105,7 @@ We now need to tell Remarkable to use our extension. We can wrap our rules in a
 
 ```js
 function anchors(md) {
-  md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
+  md.renderer.rules.heading_open = function (tokens, idx /*, options, env */) {
     return (
       '<h' +
       tokens[idx].hLevel +
@@ -116,7 +116,7 @@ function anchors(md) {
     );
   };
 
-  md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) {
+  md.renderer.rules.heading_close = function (tokens, idx /*, options, env */) {
     return (
       ' <a class="hash-link" href="#' +
       toSlug(tokens[idx - 1].content) +

docs/api-site-config.md

@@ -405,7 +405,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

packages/docusaurus/bin/docusaurus.js

@@ -16,9 +16,9 @@ const requiredVersion = require('../package.json').engines.node;
 
 if (!semver.satisfies(process.version, requiredVersion)) {
   console.log(
-    chalk.red(`\nMinimum node version not met :)`) +
+    chalk.red(`\nMinimum Node version not met :(`) +
       chalk.yellow(
-        `\nYou are using Node ${process.version}, Requirement: Node ${requiredVersion}.\n`,
+        `\n\nYou are using Node ${process.version}. We require Node ${requiredVersion} or up!\n`,
       ),
   );
   process.exit(1);
@@ -39,15 +39,15 @@ cli
   .description('Build website')
   .option(
     '--bundle-analyzer',
-    'Visualize size of webpack output files with an interactive zoomable treemap (default = false)',
+    'Visualize size of webpack output files with an interactive zoomable treemap (default: disabled)',
   )
   .option(
     '--out-dir <dir>',
-    'The full path for the new output directory, relative to the current workspace (default = build).',
+    'The full path for the new output directory, relative to the current workspace (default: build).',
   )
   .option(
     '--no-minify',
-    'Build website without minimizing JS bundles (default = false)',
+    'Build website without minimizing JS bundles (default: minification enabled)',
   )
   .action((siteDir = '.', {bundleAnalyzer, outDir, minify}) => {
     wrapCommand(build)(path.resolve(siteDir), {
@@ -69,22 +69,25 @@ cli
   .description('Deploy website to GitHub pages')
   .option(
     '--out-dir <dir>',
-    'The full path for the new output directory, relative to the current workspace (default = build).',
+    'The full path for the new output directory, relative to the current workspace (default: build).',
   )
   .action((siteDir = '.', {outDir}) => {
     wrapCommand(deploy)(path.resolve(siteDir), {outDir});
   });
 
 cli
   .command('start [siteDir]')
-  .description('Start development server')
+  .description('Start the development server')
   .option('-p, --port <port>', 'use specified port (default: 3000)')
   .option('-h, --host <host>', 'use specified host (default: localhost')
   .option(
     '--hot-only',
     'Do not fallback to page refresh if hot reload fails (default: false)',
   )
-  .option('--no-open', 'Do not open page in the browser (default: false)')
+  .option(
+    '--no-open',
+    'Do not open page in the browser (default: opening enabled)',
+  )
   .action((siteDir = '.', {port, host, hotOnly, open}) => {
     wrapCommand(start)(path.resolve(siteDir), {
       port,

packages/docusaurus/src/commands/deploy.ts

@@ -19,12 +19,12 @@ export async function deploy(
 ): Promise<void> {
   console.log('Deploy command invoked ...');
   if (!shell.which('git')) {
-    throw new Error('Sorry, this script requires git');
+    throw new Error('Git not installed or on the PATH!');
   }
 
   const gitUser = process.env.GIT_USER;
   if (!gitUser) {
-    throw new Error(`Please set the GIT_USER`);
+    throw new Error('Please set the GIT_USER environment variable!');
   }
 
   // The branch that contains the latest docs changes that will be deployed.
@@ -85,7 +85,8 @@ export async function deploy(
   // We don't allow deploying to the same branch unless it's a cross publish.
   if (currentBranch === deploymentBranch && !crossRepoPublish) {
     throw new Error(
-      `Cannot deploy from a ${deploymentBranch} branch. Only to it`,
+      `You cannot deploy from this branch (${currentBranch}).` +
+        '\nYou will need to checkout to a different branch!',
     );
   }
 
@@ -158,21 +159,28 @@ export async function deploy(
 
         const commitMessage =
           process.env.CUSTOM_COMMIT_MESSAGE ||
-          `Deploy website version based on ${currentCommit}`;
+          `Deploy website - based on ${currentCommit}`;
         const commitResults = shell.exec(`git commit -m "${commitMessage}"`);
         if (
           shell.exec(`git push --force origin ${deploymentBranch}`).code !== 0
         ) {
           throw new Error('Error: Git push failed');
         } else if (commitResults.code === 0) {
           // The commit might return a non-zero value when site is up to date.
-          const websiteURL =
-            githubHost === 'github.com'
-              ? // gh-pages hosted repo
-                `https://${organizationName}.github.io/${projectName}`
-              : // GitHub enterprise hosting.
-                `https://${githubHost}/pages/${organizationName}/${projectName}`;
-          shell.echo(`Website is live at: ${websiteURL}`);
+          let websiteURL = '';
+          if (githubHost === 'github.com') {
+            // github.io hosting
+            if (projectName.includes('.github.io')) {
+              // domain root gh-pages hosted repo
+              websiteURL = `https://${organizationName}.github.io/`;
+            } else {
+              websiteURL = `https://${organizationName}.github.io/${projectName}/`;
+            }
+          } else {
+            // GitHub enterprise hosting.
+            websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`;
+          }
+          shell.echo(`Website is live at ${websiteURL}`);
           shell.exit(0);
         }
       });

website-1.x/versioned_docs/version-1.10.x/api-site-config.md

@@ -378,7 +378,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

website-1.x/versioned_docs/version-1.11.x/api-site-config.md

@@ -390,7 +390,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

website-1.x/versioned_docs/version-1.13.0/api-site-config.md

@@ -390,7 +390,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

website-1.x/versioned_docs/version-1.14.4/api-site-config.md

@@ -406,7 +406,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

website-1.x/versioned_docs/version-1.9.x/api-site-config.md

@@ -374,7 +374,7 @@ const siteConfig = {
   },
   markdownPlugins: [
     function foo(md) {
-      md.renderer.rules.fence_custom.foo = function(
+      md.renderer.rules.fence_custom.foo = function (
         tokens,
         idx,
         options,

website/docs/lifecycle-apis.md

@@ -19,7 +19,7 @@ Example:
 
 ```js {5-7} title="docusaurus-plugin/src/index.js"
 const path = require('path');
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     getPathsToWatch() {
@@ -38,7 +38,7 @@ For example, this plugin below return a random integer between 1 to 10 as conten
 
 ```js {5-6} title="docusaurus-plugin/src/index.js"
 const path = require('path');
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     async loadContent() {
@@ -94,7 +94,7 @@ For example, this plugin below create a `/roll` page which display "You won xxxx
 ```jsx title="website/src/components/roll.js"
 import React from 'react';
 
-export default function(props) {
+export default function (props) {
   const {prizes} = props;
   const index = Math.floor(Math.random() * 3);
   return <div> You won ${prizes[index]} </div>;
@@ -151,7 +151,7 @@ You may use them to return your webpack configures conditionally.
 For example, this plugin below modify the webpack config to transpile `.foo` file.
 
 ```js {4-11} title="docusaurus-plugin/src/index.js"
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'custom-docusaurus-plugin',
     configureWebpack(config, isServer, utils) {
@@ -193,12 +193,12 @@ type Props = {
 Example:
 
 ```js {4-9} title="docusaurus-plugin/src/index.js"
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
       // Print out to console all the rendered routes
-      routesPaths.map(route => {
+      routesPaths.map((route) => {
         console.log(route);
       });
     },
@@ -213,7 +213,7 @@ Register an extra command to enhance the CLI of docusaurus. `cli` is [commander]
 Example:
 
 ```js {4-11} title="docusaurus-plugin/src/index.js"
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     extendCli(cli) {
@@ -263,7 +263,7 @@ interface HtmlTagObject {
 Example:
 
 ```js {4-28} title="docusaurus-plugin/src/index.js"
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'docusaurus-plugin',
     injectHtmlTags() {
@@ -302,7 +302,7 @@ If you use the folder directory above, your `getThemePath` can be:
 ```js {6-8} title="my-theme/src/index.js"
 const path = require('path');
 
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   return {
     name: 'name-of-my-theme',
     getThemePath() {
@@ -321,7 +321,7 @@ As an example, to make your theme load a `customCss` object from `options` passe
 ```js {7-9} title="my-theme/src/index.js"
 const path = require('path');
 
-module.exports = function(context, options) {
+module.exports = function (context, options) {
   const {customCss} = options || {};
   return {
     name: 'name-of-my-theme',
@@ -351,7 +351,7 @@ const DEFAULT_OPTIONS = {
 // A JavaScript function that returns an object.
 // `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
 // `opts` is the user-defined options.
-module.exports = function(context, opts) {
+module.exports = function (context, opts) {
   // Merge defaults with user-defined options.
   const options = {...DEFAULT_OPTIONS, ...options};