From 8f2d898f22a3d10fbb76abc866fb4b91547df33c Mon Sep 17 00:00:00 2001 From: iAmir <34688664+AmyrAhmady@users.noreply.github.com> Date: Sat, 31 Oct 2020 20:34:56 +0330 Subject: [PATCH] feat(v2): onBrokenMarkdownLinks config (#3658) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(v2): move `reportMessage` from `core/src/server/utils` to `utils` package * feat(v2): handle broken markdown links by using onBrokenLinks prop from siteconfig * feat(v2): add a new site config prop called `onBrokenMarkdownLinks` works like onBrokenLinks, but only for markdown links * feat(v2): add `onBrokenMarkdownLinks` to API docs * some changes regarding test issues after adding `onBrokenMarkdownLink` * Update website/versioned_docs/version-2.0.0-alpha.66/api/docusaurus.config.js.md Co-authored-by: Sébastien Lorber --- .../templates/bootstrap/docusaurus.config.js | 1 + .../templates/classic/docusaurus.config.js | 1 + .../templates/facebook/docusaurus.config.js | 1 + .../__fixtures__/expectedSiteConfig.js | 1 + packages/docusaurus-migrate/src/index.ts | 1 + packages/docusaurus-migrate/src/types.ts | 1 + .../src/index.ts | 22 +++++++++------ packages/docusaurus-types/src/index.d.ts | 1 + packages/docusaurus-utils/package.json | 2 ++ packages/docusaurus-utils/src/index.ts | 27 ++++++++++++++++++ .../__snapshots__/config.test.ts.snap | 1 + packages/docusaurus/src/server/brokenLinks.ts | 4 +-- .../docusaurus/src/server/configValidation.ts | 5 ++++ .../docusaurus/src/server/duplicateRoutes.ts | 3 +- packages/docusaurus/src/server/utils.ts | 28 +------------------ website/docs/api/docusaurus.config.js.md | 8 ++++++ website/docusaurus.config-blog-only.js | 1 + website/docusaurus.config.js | 1 + 18 files changed, 71 insertions(+), 38 deletions(-) diff --git a/packages/docusaurus-init/templates/bootstrap/docusaurus.config.js b/packages/docusaurus-init/templates/bootstrap/docusaurus.config.js index 1af4b31172..35a4b8f35d 100644 --- a/packages/docusaurus-init/templates/bootstrap/docusaurus.config.js +++ b/packages/docusaurus-init/templates/bootstrap/docusaurus.config.js @@ -4,6 +4,7 @@ module.exports = { url: 'https://your-docusaurus-test-site.com', baseUrl: '/', onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'facebook', // Usually your GitHub org/user name. projectName: 'docusaurus', // Usually your repo name. diff --git a/packages/docusaurus-init/templates/classic/docusaurus.config.js b/packages/docusaurus-init/templates/classic/docusaurus.config.js index 42e58acd74..5344d32216 100644 --- a/packages/docusaurus-init/templates/classic/docusaurus.config.js +++ b/packages/docusaurus-init/templates/classic/docusaurus.config.js @@ -4,6 +4,7 @@ module.exports = { url: 'https://your-docusaurus-test-site.com', baseUrl: '/', onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'facebook', // Usually your GitHub org/user name. projectName: 'docusaurus', // Usually your repo name. diff --git a/packages/docusaurus-init/templates/facebook/docusaurus.config.js b/packages/docusaurus-init/templates/facebook/docusaurus.config.js index 7c9746ce1c..a81def4de1 100644 --- a/packages/docusaurus-init/templates/facebook/docusaurus.config.js +++ b/packages/docusaurus-init/templates/facebook/docusaurus.config.js @@ -13,6 +13,7 @@ module.exports = { url: 'https://your-docusaurus-test-site.com', baseUrl: '/', onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'facebook', // Usually your GitHub org/user name. projectName: 'docusaurus', // Usually your repo name. diff --git a/packages/docusaurus-migrate/src/__tests__/__fixtures__/expectedSiteConfig.js b/packages/docusaurus-migrate/src/__tests__/__fixtures__/expectedSiteConfig.js index 6fe43d7b82..4dce50160d 100644 --- a/packages/docusaurus-migrate/src/__tests__/__fixtures__/expectedSiteConfig.js +++ b/packages/docusaurus-migrate/src/__tests__/__fixtures__/expectedSiteConfig.js @@ -31,6 +31,7 @@ module.exports = { facebookAppId: '199138890728411', }, onBrokenLinks: 'log', + onBrokenMarkdownLinks: 'log', presets: [ [ '@docusaurus/preset-classic', diff --git a/packages/docusaurus-migrate/src/index.ts b/packages/docusaurus-migrate/src/index.ts index 00d0598d9a..5805029507 100644 --- a/packages/docusaurus-migrate/src/index.ts +++ b/packages/docusaurus-migrate/src/index.ts @@ -302,6 +302,7 @@ export function createConfigFile({ favicon: siteConfig.favicon ?? '', customFields: customConfigFields, onBrokenLinks: 'log', + onBrokenMarkdownLinks: 'log', presets: [ [ '@docusaurus/preset-classic', diff --git a/packages/docusaurus-migrate/src/types.ts b/packages/docusaurus-migrate/src/types.ts index e268874608..0f18ae25d1 100644 --- a/packages/docusaurus-migrate/src/types.ts +++ b/packages/docusaurus-migrate/src/types.ts @@ -38,6 +38,7 @@ export interface VersionTwoConfig { noIndex?: boolean; githubHost?: string; onBrokenLinks: string; + onBrokenMarkdownLinks: string; plugins: Array<[string, {[key: string]: any}]>; themes?: []; presets: [[string, ClassicPresetEntries]]; diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 7945278179..a36828de7a 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -11,7 +11,12 @@ import { STATIC_DIR_NAME, DEFAULT_PLUGIN_ID, } from '@docusaurus/core/lib/constants'; -import {normalizeUrl, docuHash, aliasedSitePath} from '@docusaurus/utils'; +import { + normalizeUrl, + docuHash, + aliasedSitePath, + reportMessage, +} from '@docusaurus/utils'; import {LoadContext, Plugin, RouteConfig} from '@docusaurus/types'; import {loadSidebars, createSidebarsUtils} from './sidebars'; @@ -39,13 +44,12 @@ import {OptionsSchema} from './options'; import {flatten, keyBy, compact} from 'lodash'; import {toGlobalDataVersion} from './globalData'; import {toVersionMetadataProp} from './props'; -import chalk from 'chalk'; export default function pluginContentDocs( context: LoadContext, options: PluginOptions, ): Plugin { - const {siteDir, generatedFilesDir, baseUrl} = context; + const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context; const versionsMetadata = readVersionsMetadata({context, options}); @@ -311,11 +315,13 @@ export default function pluginContentDocs( sourceToPermalink, versionsMetadata, onBrokenMarkdownLink: (brokenMarkdownLink) => { - // TODO make this warning configurable? - console.warn( - chalk.yellow( - `Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.version.versionName}`, - ), + if (siteConfig.onBrokenMarkdownLinks === 'ignore') { + return; + } + + reportMessage( + `Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.version.versionName}`, + siteConfig.onBrokenMarkdownLinks, ); }, }; diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index a1a33461e2..af651ad8ec 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -21,6 +21,7 @@ export interface DocusaurusConfig { title: string; url: string; onBrokenLinks: ReportingSeverity; + onBrokenMarkdownLinks: ReportingSeverity; onDuplicateRoutes: ReportingSeverity; noIndex: boolean; organizationName?: string; diff --git a/packages/docusaurus-utils/package.json b/packages/docusaurus-utils/package.json index 186bf43e91..1bed792894 100644 --- a/packages/docusaurus-utils/package.json +++ b/packages/docusaurus-utils/package.json @@ -18,6 +18,8 @@ }, "license": "MIT", "dependencies": { + "@docusaurus/types": "^2.0.0-alpha.66", + "chalk": "^3.0.0", "escape-string-regexp": "^2.0.0", "fs-extra": "^8.1.0", "gray-matter": "^4.0.2", diff --git a/packages/docusaurus-utils/src/index.ts b/packages/docusaurus-utils/src/index.ts index 21c8488dee..ef693a4bbb 100644 --- a/packages/docusaurus-utils/src/index.ts +++ b/packages/docusaurus-utils/src/index.ts @@ -5,6 +5,7 @@ * LICENSE file in the root directory of this source tree. */ +import chalk from 'chalk'; import path from 'path'; import matter from 'gray-matter'; import {createHash} from 'crypto'; @@ -13,6 +14,7 @@ import kebabCase from 'lodash.kebabcase'; import escapeStringRegexp from 'escape-string-regexp'; import fs from 'fs-extra'; import {URL} from 'url'; +import {ReportingSeverity} from '@docusaurus/types'; // @ts-expect-error: no typedefs :s import resolvePathnameUnsafe from 'resolve-pathname'; @@ -436,3 +438,28 @@ export function getElementsAround( const next = aroundIndex === max ? undefined : array[aroundIndex + 1]; return {previous, next}; } + +export function reportMessage( + message: string, + reportingSeverity: ReportingSeverity, +): void { + switch (reportingSeverity) { + case 'ignore': + break; + case 'log': + console.log(chalk.bold.blue('info ') + chalk.blue(message)); + break; + case 'warn': + console.warn(chalk.bold.yellow('warn ') + chalk.yellow(message)); + break; + case 'error': + console.error(chalk.bold.red('error ') + chalk.red(message)); + break; + case 'throw': + throw new Error(message); + default: + throw new Error( + `unexpected reportingSeverity value: ${reportingSeverity}`, + ); + } +} diff --git a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap index f034064be8..9f4f77ad18 100644 --- a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap +++ b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap @@ -22,6 +22,7 @@ Object { "favicon": "img/docusaurus.ico", "noIndex": false, "onBrokenLinks": "throw", + "onBrokenMarkdownLinks": "warn", "onDuplicateRoutes": "warn", "organizationName": "endiliey", "plugins": Array [ diff --git a/packages/docusaurus/src/server/brokenLinks.ts b/packages/docusaurus/src/server/brokenLinks.ts index 89fee5b113..81bc58fac1 100644 --- a/packages/docusaurus/src/server/brokenLinks.ts +++ b/packages/docusaurus/src/server/brokenLinks.ts @@ -10,8 +10,8 @@ import resolvePathname from 'resolve-pathname'; import fs from 'fs-extra'; import {mapValues, pickBy, flatten, countBy} from 'lodash'; import {RouteConfig, ReportingSeverity} from '@docusaurus/types'; -import {removePrefix, removeSuffix} from '@docusaurus/utils'; -import {getAllFinalRoutes, reportMessage} from './utils'; +import {removePrefix, removeSuffix, reportMessage} from '@docusaurus/utils'; +import {getAllFinalRoutes} from './utils'; import path from 'path'; function toReactRouterRoutes(routes: RouteConfig[]): RRRouteConfig[] { diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts index 1295e99357..52fbb08a3d 100644 --- a/packages/docusaurus/src/server/configValidation.ts +++ b/packages/docusaurus/src/server/configValidation.ts @@ -17,6 +17,7 @@ import { export const DEFAULT_CONFIG: Pick< DocusaurusConfig, | 'onBrokenLinks' + | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' @@ -27,6 +28,7 @@ export const DEFAULT_CONFIG: Pick< | 'noIndex' > = { onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', onDuplicateRoutes: 'warn', plugins: [], themes: [], @@ -64,6 +66,9 @@ const ConfigSchema = Joi.object({ onBrokenLinks: Joi.string() .equal('ignore', 'log', 'warn', 'error', 'throw') .default(DEFAULT_CONFIG.onBrokenLinks), + onBrokenMarkdownLinks: Joi.string() + .equal('ignore', 'log', 'warn', 'error', 'throw') + .default(DEFAULT_CONFIG.onBrokenMarkdownLinks), onDuplicateRoutes: Joi.string() .equal('ignore', 'log', 'warn', 'error', 'throw') .default(DEFAULT_CONFIG.onDuplicateRoutes), diff --git a/packages/docusaurus/src/server/duplicateRoutes.ts b/packages/docusaurus/src/server/duplicateRoutes.ts index 869157b199..54af2aa70a 100644 --- a/packages/docusaurus/src/server/duplicateRoutes.ts +++ b/packages/docusaurus/src/server/duplicateRoutes.ts @@ -5,7 +5,8 @@ * LICENSE file in the root directory of this source tree. */ import {RouteConfig, ReportingSeverity} from '@docusaurus/types'; -import {getAllFinalRoutes, reportMessage} from './utils'; +import {reportMessage} from '@docusaurus/utils'; +import {getAllFinalRoutes} from './utils'; export function getAllDuplicateRoutes( pluginsRouteConfigs: RouteConfig[], diff --git a/packages/docusaurus/src/server/utils.ts b/packages/docusaurus/src/server/utils.ts index 1421604f11..e5508c2733 100644 --- a/packages/docusaurus/src/server/utils.ts +++ b/packages/docusaurus/src/server/utils.ts @@ -4,9 +4,8 @@ * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */ -import chalk from 'chalk'; import flatMap from 'lodash.flatmap'; -import {RouteConfig, ReportingSeverity} from '@docusaurus/types'; +import {RouteConfig} from '@docusaurus/types'; // Recursively get the final routes (routes with no subroutes) export function getAllFinalRoutes(routeConfig: RouteConfig[]): RouteConfig[] { @@ -15,28 +14,3 @@ export function getAllFinalRoutes(routeConfig: RouteConfig[]): RouteConfig[] { } return flatMap(routeConfig, getFinalRoutes); } - -export function reportMessage( - message: string, - reportingSeverity: ReportingSeverity, -): void { - switch (reportingSeverity) { - case 'ignore': - break; - case 'log': - console.log(chalk.bold.blue('info ') + chalk.blue(message)); - break; - case 'warn': - console.warn(chalk.bold.yellow('warn ') + chalk.yellow(message)); - break; - case 'error': - console.error(chalk.bold.red('error ') + chalk.red(message)); - break; - case 'throw': - throw new Error(message); - default: - throw new Error( - `unexpected reportingSeverity value: ${reportingSeverity}`, - ); - } -} diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index ac7ff9d5f8..df2d56dfca 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -108,6 +108,14 @@ The broken links detection is only available for a production build (`docusaurus ::: +### `onBrokenMarkdownLinks` + +- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` + +The behavior of Docusaurus, when it detects any broken markdown link. + +By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed. + ### `onDuplicateRoutes` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` diff --git a/website/docusaurus.config-blog-only.js b/website/docusaurus.config-blog-only.js index dba0207c9e..924a5a0fbf 100644 --- a/website/docusaurus.config-blog-only.js +++ b/website/docusaurus.config-blog-only.js @@ -13,6 +13,7 @@ module.exports = { baseUrl: '/blog-only/', url: 'https://v2.docusaurus.io', onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', favicon: 'img/docusaurus.ico', themes: ['@docusaurus/theme-live-codeblock'], plugins: [], diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 61f20bb75b..b8eb89cb58 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -49,6 +49,7 @@ module.exports = { baseUrl, url: 'https://v2.docusaurus.io', onBrokenLinks: isVersioningDisabled ? 'warn' : 'throw', + onBrokenMarkdownLinks: 'warn', favicon: 'img/docusaurus.ico', customFields: { description: