-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Get
yarn markdown-lint to work (#21)
* Get `yarn markdown-lint` to work On `gravitational/docs`, the `yarn markdown-lint` script runs the docs site's `remark`-based linters on the Teleport documentation content. This change ensures that the script works as expected on Docusaurus content. - Add dependencies for `yarn markdown-lint`. - Add a `build-remark` script for building remark plugins in order to run the linter. - Copy `.remarkrc.mjs` from `gravitational/docs`, but add an `updatePaths` function to remark-includes to work with the plugin's new interface. - Edit `getVersionFromFile` to accommodate linting. Get a version if the file is currently in the `content` directory, which we need to do in order to get `remarkIncludes` to work when linting files in `content`. Also add branching in `getCurrentDir` to work with the structure of the `content` directory. - Update package.json to use the versions of `remark` packages found in gravitational/docs. This minimizes the content changes we'll need to make to accommodate the linting configuration. * Respond to taraspos feedback - Revert some dependency downgrades - Remove highlightjs-terraform * Remove the external link check It is not enabled in CI, and has led to issues with rate limiting from third-party sites in the past.
- Loading branch information
Showing
16 changed files
with
1,942 additions
and
368 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -35,3 +35,6 @@ data/* | |
|
|
||
| # Migration node dependencies | ||
| .build | ||
|
|
||
| # remark node dependencies | ||
| .remark-build | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| import { resolve } from "path"; | ||
| import remarkVariables from "./.remark-build/server/remark-variables.mjs"; | ||
| import remarkIncludes from "./.remark-build/server/remark-includes.mjs"; | ||
| import remarkTOC from "./.remark-build/server/remark-toc.mjs"; | ||
| import { remarkLintTeleportDocsLinks } from "./.remark-build/server/lint-teleport-docs-links.mjs"; | ||
| import { | ||
| getVersion, | ||
| getVersionRootPath, | ||
| } from "./.remark-build/server/docs-helpers.mjs"; | ||
| import { loadConfig } from "./.remark-build/server/config-docs.mjs"; | ||
| import { | ||
| updatePathsInIncludes, | ||
| } from "./.remark-build//server/asset-path-helpers.mjs"; | ||
|
|
||
|
|
||
| const configFix = { | ||
| settings: { | ||
| bullet: "-", | ||
| ruleRepetition: 3, | ||
| fences: true, | ||
| incrementListMarker: true, | ||
| checkBlanks: true, | ||
| resourceLink: true, | ||
| emphasis: "*", | ||
| tablePipeAlign: false, | ||
| tableCellPadding: true, | ||
| listItemIndent: 1, | ||
| }, | ||
| plugins: ["frontmatter", "mdx"], | ||
| }; | ||
|
|
||
| const configLint = { | ||
| plugins: [ | ||
| "frontmatter", | ||
| "mdx", | ||
| "preset-lint-markdown-style-guide", | ||
| ["lint-table-pipe-alignment", false], | ||
| ["lint-table-cell-padding", false], | ||
| ["lint-maximum-line-length", false], | ||
| ["lint-no-consecutive-blank-lines", false], | ||
| ["lint-no-emphasis-as-heading", false], | ||
| ["lint-fenced-code-flag", { allowEmpty: true }], | ||
| ["lint-file-extension", false], | ||
| ["lint-no-duplicate-headings", false], | ||
| ["lint-list-item-spacing", { checkBlanks: true }], | ||
| ["lint-no-shell-dollars", false], | ||
| ["lint-list-item-indent", "space"], | ||
| ["lint-ordered-list-marker-value", "single"], | ||
| ["lint-maximum-heading-length", false], | ||
| ["lint-no-shortcut-reference-link", false], | ||
| ["lint-no-file-name-irregular-characters", false], | ||
| [remarkTOC], | ||
| [ | ||
| remarkIncludes, // Lints (!include.ext!) syntax | ||
| { | ||
| lint: true, | ||
| rootDir: (vfile) => getVersionRootPath(vfile.path), | ||
| updatePaths: updatePathsInIncludes, | ||
| }, | ||
| ], | ||
| [ | ||
| remarkVariables, // Lints (=variable=) syntax | ||
| { | ||
| lint: true, | ||
| variables: (vfile) => { | ||
| return loadConfig(getVersion(vfile.path)).variables || {}; | ||
| }, | ||
| }, | ||
| ], | ||
| // validate-links must be run after remarkVariables since some links | ||
| // include variables in their references, e.g., | ||
| // [CM-08 Information System Component Inventory]((=fedramp.control_url=)CM-8) | ||
| ["validate-links", { repository: false }], | ||
| [remarkLintTeleportDocsLinks], | ||
| // Disabling the remarkLintFrontmatter check until we fix | ||
| // gravitational/docs#80 | ||
| // [remarkLintFrontmatter, ["error"]], | ||
| ], | ||
| }; | ||
|
|
||
| export default process.env.FIX ? configFix : configLint; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| import { resolve } from "path"; | ||
|
|
||
| export const getVersion = (filepath: string) => { | ||
| const result = /content\/([^/]+)\/docs\//.exec(filepath); | ||
| return result ? result[1] : ""; | ||
| }; | ||
|
|
||
| /** | ||
| * Used by some remark plugins to resolve paths to assets based on the | ||
| * current docs folders. E. g. remark-includes. | ||
| */ | ||
| export const getVersionRootPath = (filepath: string) => { | ||
| const version = getVersion(filepath); | ||
|
|
||
| if (version) { | ||
| return resolve(`content/${version}`); | ||
| } else { | ||
| // CI task for linting stored files in the root of the content folder | ||
| return resolve("content"); | ||
| } | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| import type { Node } from "unist"; | ||
| import type { Transformer } from "unified"; | ||
| import type { Root, Link as MdastLink } from "mdast"; | ||
| import type { EsmNode, MdxAnyElement } from "./types-unist"; | ||
|
|
||
| import { visit } from "unist-util-visit"; | ||
| import { isExternalLink, isHash, isPage } from "../utils/url"; | ||
|
|
||
| interface ObjectHref { | ||
| src: string; | ||
| } | ||
|
|
||
| type Href = string | ObjectHref; | ||
|
|
||
| const mdxNodeTypes = new Set(["mdxJsxFlowElement", "mdxJsxTextElement"]); | ||
|
|
||
| const isMdxComponentWithHref = (node: Node): node is MdxAnyElement => { | ||
| return ( | ||
| mdxNodeTypes.has(node.type) && | ||
| (node as MdxAnyElement).attributes.some( | ||
| ({ name, value }) => name === "href" | ||
| ) | ||
| ); | ||
| }; | ||
|
|
||
| const isAnAbsoluteDocsLink = (href: string): boolean => { | ||
| return ( | ||
| href.startsWith("/docs") || href.startsWith("https://goteleport.com/docs") | ||
| ); | ||
| }; | ||
|
|
||
| export function remarkLintTeleportDocsLinks(): Transformer { | ||
| return (root: Root, vfile) => { | ||
| visit(root, (node: Node) => { | ||
| if ( | ||
| node.type == "link" && | ||
| isAnAbsoluteDocsLink((node as MdastLink).url) | ||
| ) { | ||
| vfile.message( | ||
| `Link reference ${ | ||
| (node as MdastLink).url | ||
| } must be a relative link to an *.mdx page`, | ||
| node.position | ||
| ); | ||
| return; | ||
| } | ||
|
|
||
| if (isMdxComponentWithHref(node)) { | ||
| const hrefAttribute = node.attributes.find( | ||
| ({ name }) => name === "href" | ||
| ); | ||
|
|
||
| if (isAnAbsoluteDocsLink(hrefAttribute.value as string)) { | ||
| vfile.message( | ||
| `Component href ${hrefAttribute.value} must be a relative link to an *.mdx page`, | ||
| node.position | ||
| ); | ||
| } | ||
| } | ||
| }); | ||
| }; | ||
| } |
Oops, something went wrong.