Support building and deploying from multiple json configs (#838)

.travis.yml

@@ -2,13 +2,20 @@ language: node_js
 node_js:
   - '8'
 deploy:
-  provider: script
-  script: cd docs && ../index.js build && ../index.js deploy --travis
-  skip_cleanup: true
-  on:
-    repo: MarkBind/markbind
-    tags: true
-    condition: $TRAVIS_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+
+  # deploy on release, to markbind.org
+  - provider: script
+    script: cd docs && ../index.js build -s ug-site.json && ../index.js deploy -s ug-site.json --travis
+    skip_cleanup: true
+    on:
+      repo: MarkBind/markbind
+      tags: true
+      condition: $TRAVIS_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+
+  # deploy on any commit to master, to markbind.org/devdocs
+  - provider: script
+    script: cd docs && ../index.js build -s dg-site.json && ../index.js deploy -s dg-site.json --travis
+    skip_cleanup: true
+    on:
+      repo: MarkBind/markbind
 cache:
   directories:
     - node_modules

docs/_markbind/headers/header.md

@@ -3,10 +3,10 @@
   <navbar type="dark">
     <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand"><img src="{{baseUrl}}/images/logo-darkbackground.png" height="20" /></a>
     <li><a href="{{baseUrl}}/index.html" class="nav-link">HOME</a></li>
-    <li><a href="{{baseUrl}}/userGuide/index.html" class="nav-link">USER GUIDE</a></li>
+    <div tags="environment--ug"><li><a href="{{baseUrl}}/userGuide/index.html" class="nav-link">USER GUIDE</a></li></div>
+    <div tags="environment--dg"><li><a href="{{baseUrl}}/devGuide/index.html" class="nav-link">DEVELOPER GUIDE</a></li></div>
     <li><a href="{{baseUrl}}/showcase.html" class="nav-link">SHOWCASE</a></li>
     <li><a href="{{baseUrl}}/about.html" class="nav-link">ABOUT</a></li>
-    <li><a href="{{baseUrl}}/devGuide/index.html" class="nav-link">DEVELOPER GUIDE</a></li>
     <li>
       <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link"><md>:fab-github:</md></a>
     </li>

docs/dg-site.json

@@ -0,0 +1,46 @@
+{
+  "baseUrl": "/devdocs",
+  "titlePrefix": "MarkBind",
+  "pages": [
+    {
+      "glob": "**/*.mbd"
+    },
+    {
+      "glob": "*.md"
+    },
+    {
+      "src": "index.md",
+      "searchable": "no"
+    },
+    {
+      "glob": "devGuide/*.md"
+    }
+  ],
+  "headingIndexingLevel": 6,
+  "ignore": [
+    "_markbind",
+    "_site/*",
+    "lib/*",
+    "*.json",
+    "*.md",
+    "*.mbd",
+    "*.mbdf",
+    "*.njk",
+    ".git/*",
+    "*.pptx",
+    "CNAME"
+  ],
+  "plugins" : [
+    "filterTags"
+  ],
+  "pluginsContext" : {
+    "filterTags" : {
+      "tags": ["environment--dg"]
+    }
+  },
+  "deploy": {
+    "message": "Dev Site Update.",
+    "repo": "https://github.com/MarkBind/devdocs.git",
+    "branch": "gh-pages"
+  }
+}

docs/index.md

@@ -4,6 +4,8 @@
   footer: footer.md
 </frontmatter>
 
+<div tags="environment--ug">
+
 <h1 class="display-3"><md>**MarkBind**</md></h1>
 
 <span class="lead">
@@ -166,3 +168,19 @@ Installing MarkBind takes just one command. Creating a new MarkBind site too tak
 As MarkBind is also optimized for project documentation, it can easily [integrate with the workflow of a software project](userGuide/markBindInTheProjectWorkflow.html).
 
 <b-btn variant="primary" href="userGuide/">Get Started</b-btn>
+
+</div>
+
+<div tags="environment--dg">
+
+## Developer Guide
+
+<box type="warning">
+    If you are a user, please visit <a href="https://markbind.org">MarkBind.org</a> instead.
+</box>
+
+This is the latest Developer Guide for MarkBind.
+
+For contributors: please access the Developer Guide [here](devGuide/index.html)
+
+</div>

docs/site.json

@@ -29,20 +29,16 @@
     },
     {
       "glob": "devGuide/*.md"
-    },
-    {
-      "src": "devGuide/index.md",
-      "searchable": "no"
-    },
-    {
-      "src": "devGuide/devGuide.md",
-      "searchable": "no"
-    },
-    {
-      "src": "devGuide/maintainerGuide.md",
-      "searchable": "no"
     }
   ],
+  "plugins" : [
+    "filterTags"
+  ],
+  "pluginsContext" : {
+    "filterTags" : {
+      "tags": ["environment--ug", "environment--dg"]
+    }
+  },
   "headingIndexingLevel": 6,
   "ignore": [
     "_markbind",
@@ -54,11 +50,10 @@
     "*.mbdf",
     "*.njk",
     ".git/*",
-    "*.pptx"
+    "*.pptx",
+    "CNAME"
   ],
   "deploy": {
-    "message": "Site Update.",
-    "repo": "https://github.com/MarkBind/markbind.github.io.git",
-    "branch": "master"
+    "message": "Site Update."
   }
 }

docs/ug-site.json

@@ -0,0 +1,57 @@
+{
+  "baseUrl": "",
+  "titlePrefix": "MarkBind",
+  "pages": [
+    {
+      "glob": "**/*.mbd"
+    },
+    {
+      "glob": "*.md"
+    },
+    {
+      "src": "index.md",
+      "searchable": "no"
+    },
+    {
+      "glob": "userGuide/*.md"
+    },
+    {
+      "src": "userGuide/fullSyntaxReference.md",
+      "searchable": "no"
+    },
+    {
+      "src": "userGuide/syntaxCheatSheet.md",
+      "searchable": "no"
+    },
+    {
+      "src": "userGuide/readerFacingFeatures.md",
+      "searchable": "no"
+    }
+  ],
+  "plugins" : [
+    "filterTags"
+  ],
+  "pluginsContext" : {
+    "filterTags" : {
+      "tags": ["environment--ug"]
+    }
+  },
+  "headingIndexingLevel": 6,
+  "ignore": [
+    "_markbind",
+    "_site/*",
+    "lib/*",
+    "*.json",
+    "*.md",
+    "*.mbd",
+    "*.mbdf",
+    "*.njk",
+    ".git/*",
+    "*.pptx"
+  ],
+  "deploy": {
+    "message": "Site Update.",
+    "repo": "https://github.com/MarkBind/markbind.github.io.git",
+    "branch": "master"
+  }
+}

docs/userGuide/cliCommands.md

@@ -42,6 +42,9 @@ MarkBind Command Line Interface (CLI) can be run in the following ways:
 * `--baseUrl <base>`<br>
   Override the `baseUrl` property (read from the `site.json`) with the give `<base>` value.<br>
   {{ icon_example }} `--baseUrl staging`
+* `-s <file>`, `--site-config <file>`<br>
+  Specify the site config file (default: `site.json`)<br>
+  {{ icon_example }} `-s otherSite.json`
 
 **{{ icon_examples }}**
 * `markbind build`

docs/userGuide/deployingTheSite.md

@@ -18,7 +18,16 @@ Generic steps for deploying a MarkBind site:
 1. Set the [`baseUrl` property of the `site.json` file](siteConfiguration.html#baseUrl) to match the deploy location.
 1. (Optional) Use the [`markbind serve` command](cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected.
 1. Use the [`markbind build` command](cliCommands.html#build-command) to generate the site from source files. That command puts the generated site files in a directory named `_site` (you can change the output directory using parameters supplied to the command).
-1. Upload the site files to the Web server. The sections below explains how to automate this step for when deploying to some online platforms.
+1. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
+
+
+Steps for deploying multiple MarkBind sites:
+1. Create multiple `site.json` files. Ensure that the [`baseUrl` property of each `site.json` file](siteConfiguration.html#baseUrl) matches its deploy location.
+1. (Optional) Use the [`markbind serve -s <file>` command](cliCommands.html#serve-command) to stage each site locally and confirm the contents are as expected.
+1. For each site:
+    1. Use the [`markbind build -s <file>` command](cliCommands#build-command) to generate the site from source files.
+    1. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
+
 
 ## Deploying to Github Pages
 

index.js

@@ -88,7 +88,7 @@ program
   .action((userSpecifiedRoot, options) => {
     let rootFolder;
     try {
-      rootFolder = cliUtil.findRootFolder(userSpecifiedRoot);
+      rootFolder = cliUtil.findRootFolder(userSpecifiedRoot, options.siteConfig);
     } catch (err) {
       handleError(err);
     }
@@ -189,10 +189,11 @@ program
   .alias('d')
   .description('deploy the site to the repo\'s Github pages.')
   .option('-t, --travis [tokenVar]', 'deploy the site in Travis [GITHUB_TOKEN]')
+  .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
   .action((options) => {
     const rootFolder = path.resolve(process.cwd());
     const outputRoot = path.join(rootFolder, '_site');
-    new Site(rootFolder, outputRoot).deploy(options.travis)
+    new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig).deploy(options.travis)
       .then(() => {
         logger.info('Deployed!');
       })
@@ -205,20 +206,21 @@ program
   .alias('b')
   .option('--baseUrl [baseUrl]',
           'optional flag which overrides baseUrl in site.json, leave argument empty for empty baseUrl')
+  .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
   .description('build a website')
   .action((userSpecifiedRoot, output, options) => {
     // if --baseUrl contains no arguments (options.baseUrl === true) then set baseUrl to empty string
     const baseUrl = _.isBoolean(options.baseUrl) ? '' : options.baseUrl;
     let rootFolder;
     try {
-      rootFolder = cliUtil.findRootFolder(userSpecifiedRoot);
+      rootFolder = cliUtil.findRootFolder(userSpecifiedRoot, options.siteConfig);
     } catch (err) {
       handleError(err);
     }
     const defaultOutputRoot = path.join(rootFolder, '_site');
     const outputFolder = output ? path.resolve(process.cwd(), output) : defaultOutputRoot;
     printHeader();
-    new Site(rootFolder, outputFolder)
+    new Site(rootFolder, outputFolder, undefined, undefined, options.siteConfig)
       .generate(baseUrl)
       .then(() => {
         logger.info('Build success!');