From e9e5667aab835771aa44b7ca630126a82a3fac2d Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Wed, 5 Jun 2019 15:37:04 -0700 Subject: [PATCH 1/6] Add new config DOC_FOLDERS --- .../gatsby/src/gatsby-config/get-gatsby-config.js | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/modules/gatsby/src/gatsby-config/get-gatsby-config.js b/modules/gatsby/src/gatsby-config/get-gatsby-config.js index 36848679..79a1f7ed 100644 --- a/modules/gatsby/src/gatsby-config/get-gatsby-config.js +++ b/modules/gatsby/src/gatsby-config/get-gatsby-config.js @@ -7,6 +7,7 @@ const CONFIG_SCHEMA = require('./config-schema'); const defaults = { logLevel: 3, DOC_FOLDER: '/docs', + DOC_FOLDERS: [], ROOT_FOLDER: './', DIR_NAME: 'website', EXAMPLES: [], @@ -323,6 +324,19 @@ module.exports = function getGatsbyConfig(config) { // conditional plug-ins - only added depending on options on config + if (paddedConfig.DOC_FOLDERS && paddedConfig.DOC_FOLDERS.length > 0) { + // Generates gatsby nodes for markdown files and JSON file in the in the docs folder + paddedConfig.DOC_FOLDERS.forEach(folderPath => { + gatsbyConfig.plugins.push({ + resolve: 'gatsby-source-filesystem', + options: { + name: 'docs', + path: folderPath + } + }); + }) + } + if (paddedConfig.DIR_NAME) { // Generates gatsby nodes for files in the website's src folder gatsbyConfig.plugins.push({ From dec067748b7dcca2645e6a84deae4bce29bd6304 Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Thu, 6 Jun 2019 13:37:01 -0700 Subject: [PATCH 2/6] Add new config DOC_FOLDERS to support multiple doc folders --- docs/gatsby/api-reference/ocular-config.md | 2 ++ .../src/gatsby-config/config-schema.json | 12 ++++++++++ .../src/gatsby-config/get-gatsby-config.js | 22 ++++++++++--------- .../process-nodes/process-nodes-markdown.js | 20 +++++++++++++---- modules/gatsby/src/utils/validate-config.js | 8 ++++++- 5 files changed, 49 insertions(+), 15 deletions(-) diff --git a/docs/gatsby/api-reference/ocular-config.md b/docs/gatsby/api-reference/ocular-config.md index 79cfa571..adf25117 100644 --- a/docs/gatsby/api-reference/ocular-config.md +++ b/docs/gatsby/api-reference/ocular-config.md @@ -18,6 +18,8 @@ | `EXAMPLES` | `Array` | See below | | `INDEX_PAGE_URL` | `String` | Optional URL to a replacement component for the home page. | | `DOC_PAGE_URL` | `String` | Optional URL to a replacement component for doc pages. | +| `DOC_FOLDER` | `String` | The path to the doc folder. | +| `DOC_FOLDERS` | `Array` | A set of paths to the doc folders. If `DOC_FOLDER` is set, `DOC_FOLDERS` will be omitted.| | `EXAMPLE_GALLERY_PAGE_URL` | `String` | Optional URL to a replacement component for the example gallery page (`/examples`). | | `EXAMPLE_PAGE_URL` | `String` | Optional URL to a replacement component for the default example page. Normally `EXAMPLES[].componentUrl` is used instead. | diff --git a/modules/gatsby/src/gatsby-config/config-schema.json b/modules/gatsby/src/gatsby-config/config-schema.json index 56a25371..07272e97 100644 --- a/modules/gatsby/src/gatsby-config/config-schema.json +++ b/modules/gatsby/src/gatsby-config/config-schema.json @@ -15,6 +15,18 @@ } }, + "DOC_FOLDERS": { + "arrayValidate": { + "allowEmpty": true, + "constraint": { + "anyString": { + "allowEmpty": true, + "message": "should be the local path to the doc folder." + } + } + } + }, + "ROOT_FOLDER": { "anyString": { "allowEmpty": true, diff --git a/modules/gatsby/src/gatsby-config/get-gatsby-config.js b/modules/gatsby/src/gatsby-config/get-gatsby-config.js index 79a1f7ed..ec9cb186 100644 --- a/modules/gatsby/src/gatsby-config/get-gatsby-config.js +++ b/modules/gatsby/src/gatsby-config/get-gatsby-config.js @@ -6,7 +6,7 @@ const CONFIG_SCHEMA = require('./config-schema'); const defaults = { logLevel: 3, - DOC_FOLDER: '/docs', + DOC_FOLDER: '', DOC_FOLDERS: [], ROOT_FOLDER: './', DIR_NAME: 'website', @@ -109,15 +109,6 @@ module.exports = function getGatsbyConfig(config) { } }, - // Generates gatsby nodes for markdown files and JSON file in the in the docs folder - { - resolve: 'gatsby-source-filesystem', - options: { - name: 'docs', - path: paddedConfig.DOC_FOLDER - } - }, - // Transforms markdown (.md) nodes, converting the raw markdown to HTML { resolve: 'gatsby-transformer-remark', @@ -324,6 +315,17 @@ module.exports = function getGatsbyConfig(config) { // conditional plug-ins - only added depending on options on config + // Generates gatsby nodes for markdown files and JSON file in the in the docs folder + if (paddedConfig.DOC_FOLDER) { + gatsbyConfig.plugins.push({ + resolve: 'gatsby-source-filesystem', + options: { + name: 'docs', + path: paddedConfig.DOC_FOLDER + } + }); + } + if (paddedConfig.DOC_FOLDERS && paddedConfig.DOC_FOLDERS.length > 0) { // Generates gatsby nodes for markdown files and JSON file in the in the docs folder paddedConfig.DOC_FOLDERS.forEach(folderPath => { diff --git a/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js b/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js index 0898cbe3..6b81f924 100644 --- a/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js +++ b/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js @@ -50,12 +50,24 @@ module.exports.processNewMarkdownNode = function processNewMarkdownNode( // Update path let relPath = node.fields.slug; if (node.fileAbsolutePath) { - const index = node.fileAbsolutePath.indexOf('docs'); - if (index !== -1) { - relPath = node.fileAbsolutePath.slice(index); + + const {ocularConfig} = global; + // TODO(@javidhsueh): we might deprecate DOC_FOLDER soon. + if (ocularConfig.DOC_FOLDER) { + const src = path.resolve(ocularConfig.DOC_FOLDER); + const pathBeforeDir = src.substr(0, src.lastIndexOf('/') + 1); + relPath = node.fileAbsolutePath.replace(pathBeforeDir, ''); + } else if (ocularConfig.DOC_FOLDERS) { + const index = ocularConfig.DOC_FOLDERS.findIndex( + folder => node.fileAbsolutePath.includes(path.resolve(folder)) + ); + if (index !== -1) { + const src = path.resolve(ocularConfig.DOC_FOLDERS[index]); + const pathBeforeDir = src.substr(0, src.lastIndexOf('/') + 1); + relPath = node.fileAbsolutePath.replace(pathBeforeDir, ''); + } } - // relPath = path.relative(siteConfig.ROOT_FOLDER, node.fileAbsolutePath); const basename = path.basename(relPath, '.md'); const dirname = path.dirname(relPath); relPath = basename === 'README' ? dirname : `${dirname}/${basename}`; diff --git a/modules/gatsby/src/utils/validate-config.js b/modules/gatsby/src/utils/validate-config.js index 1d2667de..429b22b7 100644 --- a/modules/gatsby/src/utils/validate-config.js +++ b/modules/gatsby/src/utils/validate-config.js @@ -63,8 +63,14 @@ validate.validators.arrayValidate = function arrayValidate( if (value.length === 0 && !allowEmpty) { return `${key} cannot be empty.`; } + console.log(value, constraint); // check every element in the array - const messages = value.map(v => validate(v, constraint)).filter(Boolean); + const messages = value.map(v => { + if (validate.isObject(v)) { + return validate(v, constraint); + } + return validate.single(v, constraint); + }).filter(Boolean); if (messages.length > 0) { // consolidate error messages of each element return messages.map((m, idx) => { From 74bb1e9b3b02013b1ec4b831c4a7cb7412b1d972 Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Thu, 6 Jun 2019 13:39:49 -0700 Subject: [PATCH 3/6] remove console.log --- modules/gatsby/src/gatsby-config/config-schema.json | 1 - modules/gatsby/src/utils/validate-config.js | 1 - 2 files changed, 2 deletions(-) diff --git a/modules/gatsby/src/gatsby-config/config-schema.json b/modules/gatsby/src/gatsby-config/config-schema.json index 07272e97..3d997e75 100644 --- a/modules/gatsby/src/gatsby-config/config-schema.json +++ b/modules/gatsby/src/gatsby-config/config-schema.json @@ -20,7 +20,6 @@ "allowEmpty": true, "constraint": { "anyString": { - "allowEmpty": true, "message": "should be the local path to the doc folder." } } diff --git a/modules/gatsby/src/utils/validate-config.js b/modules/gatsby/src/utils/validate-config.js index 429b22b7..bbbc8276 100644 --- a/modules/gatsby/src/utils/validate-config.js +++ b/modules/gatsby/src/utils/validate-config.js @@ -63,7 +63,6 @@ validate.validators.arrayValidate = function arrayValidate( if (value.length === 0 && !allowEmpty) { return `${key} cannot be empty.`; } - console.log(value, constraint); // check every element in the array const messages = value.map(v => { if (validate.isObject(v)) { From 763272373788eca46e271e6bddb29a34259b62e0 Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Thu, 6 Jun 2019 13:55:52 -0700 Subject: [PATCH 4/6] Fix tests --- modules/gatsby/src/utils/validate-config.js | 3 +++ .../gatsby/test/utils/validate-config.spec.js | 16 ++++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/gatsby/src/utils/validate-config.js b/modules/gatsby/src/utils/validate-config.js index bbbc8276..71123751 100644 --- a/modules/gatsby/src/utils/validate-config.js +++ b/modules/gatsby/src/utils/validate-config.js @@ -56,6 +56,9 @@ validate.validators.arrayValidate = function arrayValidate( key ) { const {allowEmpty, constraint} = options; + if (!value && allowEmpty) { + return null; + } // check value is array if (!validate.isArray(value)) { return `${key} needs to be an array.`; diff --git a/modules/gatsby/test/utils/validate-config.spec.js b/modules/gatsby/test/utils/validate-config.spec.js index fb38c75c..e46bc3cc 100644 --- a/modules/gatsby/test/utils/validate-config.spec.js +++ b/modules/gatsby/test/utils/validate-config.spec.js @@ -6,6 +6,7 @@ import CONFIG_SCHEMA from '../../src/gatsby-config/config-schema'; const GOOD_CONFIG = { logLevel: 4, DOC_FOLDER: `./docs/`, + DOC_FOLDERS: [], ROOT_FOLDER: `/`, DIR_NAME: '/', EXAMPLES: [], @@ -51,17 +52,16 @@ test('validateConfig', t => { t.deepEquals( validateConfig({}, CONFIG_SCHEMA), [ - "Examples can't be blank,Examples EXAMPLES needs to be an array.", + 'Examples can\'t be blank', 'Docs DOCS needs to be an object.', - "Project type can't be blank", - "Project url can't be blank", - "Project desc can't be blank,Project desc should be the project's description", + 'Project type can\'t be blank', + 'Project url can\'t be blank', + 'Project desc can\'t be blank,Project desc should be the project\'s description', 'Path prefix should be the prefix added to all paths on the site', - 'Projects PROJECTS needs to be an array.', - "Home heading can't be blank,Home heading should be ...", - "Home bullets can't be blank,Home bullets HOME_BULLETS needs to be an array.", + 'Home heading can\'t be blank,Home heading should be ...', + 'Home bullets can\'t be blank,Home bullets HOME_BULLETS needs to be an array.', 'Theme overrides THEME_OVERRIDES needs to be an array.', - "Additional links can't be blank,Additional links ADDITIONAL_LINKS needs to be an array.", + 'Additional links can\'t be blank', 'Webpack webpack needs to be an object.' ], 'Get all errors when config is empty' From bb9711cb45943bb38185a8902326c63e0e4139c7 Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Fri, 7 Jun 2019 11:51:30 -0700 Subject: [PATCH 5/6] remove comment, remove "DOC_FOLDER" from documentation, add messages to warn the config to be deprecated soon. --- docs/gatsby/api-reference/ocular-config.md | 3 +-- .../src/gatsby-node/process-nodes/process-nodes-markdown.js | 1 - modules/gatsby/src/utils/validate-config.js | 4 ++++ 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/gatsby/api-reference/ocular-config.md b/docs/gatsby/api-reference/ocular-config.md index adf25117..7035e6ed 100644 --- a/docs/gatsby/api-reference/ocular-config.md +++ b/docs/gatsby/api-reference/ocular-config.md @@ -18,8 +18,7 @@ | `EXAMPLES` | `Array` | See below | | `INDEX_PAGE_URL` | `String` | Optional URL to a replacement component for the home page. | | `DOC_PAGE_URL` | `String` | Optional URL to a replacement component for doc pages. | -| `DOC_FOLDER` | `String` | The path to the doc folder. | -| `DOC_FOLDERS` | `Array` | A set of paths to the doc folders. If `DOC_FOLDER` is set, `DOC_FOLDERS` will be omitted.| +| `DOC_FOLDERS` | `Array` | A set of paths to the doc folders to source all markdown files. | | `EXAMPLE_GALLERY_PAGE_URL` | `String` | Optional URL to a replacement component for the example gallery page (`/examples`). | | `EXAMPLE_PAGE_URL` | `String` | Optional URL to a replacement component for the default example page. Normally `EXAMPLES[].componentUrl` is used instead. | diff --git a/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js b/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js index 6b81f924..5f71b567 100644 --- a/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js +++ b/modules/gatsby/src/gatsby-node/process-nodes/process-nodes-markdown.js @@ -52,7 +52,6 @@ module.exports.processNewMarkdownNode = function processNewMarkdownNode( if (node.fileAbsolutePath) { const {ocularConfig} = global; - // TODO(@javidhsueh): we might deprecate DOC_FOLDER soon. if (ocularConfig.DOC_FOLDER) { const src = path.resolve(ocularConfig.DOC_FOLDER); const pathBeforeDir = src.substr(0, src.lastIndexOf('/') + 1); diff --git a/modules/gatsby/src/utils/validate-config.js b/modules/gatsby/src/utils/validate-config.js index 71123751..78702064 100644 --- a/modules/gatsby/src/utils/validate-config.js +++ b/modules/gatsby/src/utils/validate-config.js @@ -125,15 +125,19 @@ validate.validators.requiredForGithubProject = function prerequisite( return null; }; +const WILL_DEPRECATED = ['DOC_FOLDER']; + // validate the config and return a list of warnings. module.exports = function validateConfig(config, constraints) { // check unused/deprecated config const unusedProperties = Object.keys(config).filter(key => !constraints[key]); + const deprecatedProperties = Object.keys(config).filter(key => WILL_DEPRECATED.includes(key)); // check config, validate function will return a object with corresponding warnings. // ex: {GITHUB_KEY: ['must be provided if your project is hosted on Github.']} const messages = validate(config, constraints) || {}; const allMessages = [ ...unusedProperties.map(key => `${key} is not used in the gatsby config.`), + ...deprecatedProperties.map(key => `${key} will be deprecated soon.`), ...Object.keys(messages).map(key => messages[key].toString()) ]; // print out all warnings From 003d2bdd9f523814dddfbb210db7e2c2eae8f522 Mon Sep 17 00:00:00 2001 From: Javid Hsueh Date: Fri, 7 Jun 2019 11:55:08 -0700 Subject: [PATCH 6/6] fix tests --- modules/gatsby/test/utils/validate-config.spec.js | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/gatsby/test/utils/validate-config.spec.js b/modules/gatsby/test/utils/validate-config.spec.js index e46bc3cc..1b40a414 100644 --- a/modules/gatsby/test/utils/validate-config.spec.js +++ b/modules/gatsby/test/utils/validate-config.spec.js @@ -5,7 +5,6 @@ import CONFIG_SCHEMA from '../../src/gatsby-config/config-schema'; const GOOD_CONFIG = { logLevel: 4, - DOC_FOLDER: `./docs/`, DOC_FOLDERS: [], ROOT_FOLDER: `/`, DIR_NAME: '/', @@ -67,6 +66,19 @@ test('validateConfig', t => { 'Get all errors when config is empty' ); + // will deprecated configs + t.deepEquals( + validateConfig( + { + ...GOOD_CONFIG, + DOC_FOLDER: './docs' + }, + CONFIG_SCHEMA + ), + ['DOC_FOLDER will be deprecated soon.'], + 'Check deprecated configs' + ); + // logLevel t.deepEquals( validateConfig(