build(docs): add `editLink: ` to MD frontmatter
Add a YAML front-matter entry called `editLink` to Markdown files in Vitepress, e.g. ```markdown --- editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/src/schemas/config.schema.yaml" --- Here is my markdown file! ``` Although Vitepress doesn't officially support adding a URL as a `editLink:` YAML front-matter, we can add a custom `editLink` function to our Vitepress config that does allow it.
This commit is contained in:
parent
7cb009cd38
commit
57ee181fad
|
@ -34,7 +34,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync }
|
||||||
import { exec } from 'child_process';
|
import { exec } from 'child_process';
|
||||||
import { globby } from 'globby';
|
import { globby } from 'globby';
|
||||||
import { JSDOM } from 'jsdom';
|
import { JSDOM } from 'jsdom';
|
||||||
import type { Code, ListItem, Root, Text } from 'mdast';
|
import type { Code, ListItem, Root, Text, YAML } from 'mdast';
|
||||||
import { posix, dirname, relative, join } from 'path';
|
import { posix, dirname, relative, join } from 'path';
|
||||||
import prettier from 'prettier';
|
import prettier from 'prettier';
|
||||||
import { remark } from 'remark';
|
import { remark } from 'remark';
|
||||||
|
@ -209,6 +209,8 @@ interface TransformMarkdownAstOptions {
|
||||||
originalFilename: string;
|
originalFilename: string;
|
||||||
/** If `true`, add a warning that the file is autogenerated */
|
/** If `true`, add a warning that the file is autogenerated */
|
||||||
addAutogeneratedWarning?: boolean;
|
addAutogeneratedWarning?: boolean;
|
||||||
|
/** If `true`, adds an `editLink: "https://..."` YAML frontmatter field */
|
||||||
|
addEditLink?: boolean;
|
||||||
/**
|
/**
|
||||||
* If `true`, remove the YAML metadata from the Markdown input.
|
* If `true`, remove the YAML metadata from the Markdown input.
|
||||||
* Generally, YAML metadata is only used for Vitepress.
|
* Generally, YAML metadata is only used for Vitepress.
|
||||||
|
@ -231,6 +233,7 @@ interface TransformMarkdownAstOptions {
|
||||||
export function transformMarkdownAst({
|
export function transformMarkdownAst({
|
||||||
originalFilename,
|
originalFilename,
|
||||||
addAutogeneratedWarning,
|
addAutogeneratedWarning,
|
||||||
|
addEditLink,
|
||||||
removeYAML,
|
removeYAML,
|
||||||
}: TransformMarkdownAstOptions) {
|
}: TransformMarkdownAstOptions) {
|
||||||
return (tree: Root, _file?: any): Root => {
|
return (tree: Root, _file?: any): Root => {
|
||||||
|
@ -270,6 +273,25 @@ export function transformMarkdownAst({
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if (addEditLink) {
|
||||||
|
// add originalFilename as custom editLink in YAML frontmatter
|
||||||
|
let yamlFrontMatter: YAML;
|
||||||
|
if (astWithTransformedBlocks.children[0].type === 'yaml') {
|
||||||
|
yamlFrontMatter = astWithTransformedBlocks.children[0];
|
||||||
|
} else {
|
||||||
|
yamlFrontMatter = {
|
||||||
|
type: 'yaml',
|
||||||
|
value: '',
|
||||||
|
};
|
||||||
|
astWithTransformedBlocks.children.unshift(yamlFrontMatter);
|
||||||
|
}
|
||||||
|
const filePathFromRoot = posix.join('packages/mermaid', originalFilename);
|
||||||
|
// TODO, should we replace this with proper YAML parsing?
|
||||||
|
yamlFrontMatter.value += `\neditLink: ${JSON.stringify(
|
||||||
|
`https://github.com/mermaid-js/mermaid/edit/develop/${filePathFromRoot}`
|
||||||
|
)}`;
|
||||||
|
}
|
||||||
|
|
||||||
if (removeYAML) {
|
if (removeYAML) {
|
||||||
const firstNode = astWithTransformedBlocks.children[0];
|
const firstNode = astWithTransformedBlocks.children[0];
|
||||||
if (firstNode.type == 'yaml') {
|
if (firstNode.type == 'yaml') {
|
||||||
|
@ -306,6 +328,7 @@ const transformMarkdown = (file: string) => {
|
||||||
// mermaid project specific plugin
|
// mermaid project specific plugin
|
||||||
originalFilename: file,
|
originalFilename: file,
|
||||||
addAutogeneratedWarning: !noHeader,
|
addAutogeneratedWarning: !noHeader,
|
||||||
|
addEditLink: noHeader,
|
||||||
removeYAML: !noHeader,
|
removeYAML: !noHeader,
|
||||||
})
|
})
|
||||||
.processSync(doc)
|
.processSync(doc)
|
||||||
|
@ -427,6 +450,7 @@ async function transormJsonSchema(file: string) {
|
||||||
// mermaid project specific plugin
|
// mermaid project specific plugin
|
||||||
originalFilename: file,
|
originalFilename: file,
|
||||||
addAutogeneratedWarning: !noHeader,
|
addAutogeneratedWarning: !noHeader,
|
||||||
|
addEditLink: noHeader,
|
||||||
removeYAML: !noHeader,
|
removeYAML: !noHeader,
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|
|
@ -105,6 +105,27 @@ This Markdown should be kept.
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it('should add an editLink in the YAML frontmatter if `addEditLink: true`', async () => {
|
||||||
|
const contents = `---
|
||||||
|
title: Flowcharts Syntax
|
||||||
|
---
|
||||||
|
|
||||||
|
This Markdown should be kept.
|
||||||
|
`;
|
||||||
|
const withYaml = (
|
||||||
|
await remarkBuilder()
|
||||||
|
.use(transformMarkdownAst, { originalFilename, addEditLink: true })
|
||||||
|
.process(contents)
|
||||||
|
).toString();
|
||||||
|
expect(withYaml).toEqual(`---
|
||||||
|
title: Flowcharts Syntax
|
||||||
|
editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md"
|
||||||
|
---
|
||||||
|
|
||||||
|
This Markdown should be kept.
|
||||||
|
`);
|
||||||
|
});
|
||||||
|
|
||||||
describe('transformToBlockQuote', () => {
|
describe('transformToBlockQuote', () => {
|
||||||
// TODO Is there a way to test this with --vitepress given as a process argument?
|
// TODO Is there a way to test this with --vitepress given as a process argument?
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue