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 { globby } from 'globby';
|
||||
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 prettier from 'prettier';
|
||||
import { remark } from 'remark';
|
||||
|
@ -209,6 +209,8 @@ interface TransformMarkdownAstOptions {
|
|||
originalFilename: string;
|
||||
/** If `true`, add a warning that the file is autogenerated */
|
||||
addAutogeneratedWarning?: boolean;
|
||||
/** If `true`, adds an `editLink: "https://..."` YAML frontmatter field */
|
||||
addEditLink?: boolean;
|
||||
/**
|
||||
* If `true`, remove the YAML metadata from the Markdown input.
|
||||
* Generally, YAML metadata is only used for Vitepress.
|
||||
|
@ -231,6 +233,7 @@ interface TransformMarkdownAstOptions {
|
|||
export function transformMarkdownAst({
|
||||
originalFilename,
|
||||
addAutogeneratedWarning,
|
||||
addEditLink,
|
||||
removeYAML,
|
||||
}: TransformMarkdownAstOptions) {
|
||||
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) {
|
||||
const firstNode = astWithTransformedBlocks.children[0];
|
||||
if (firstNode.type == 'yaml') {
|
||||
|
@ -306,6 +328,7 @@ const transformMarkdown = (file: string) => {
|
|||
// mermaid project specific plugin
|
||||
originalFilename: file,
|
||||
addAutogeneratedWarning: !noHeader,
|
||||
addEditLink: noHeader,
|
||||
removeYAML: !noHeader,
|
||||
})
|
||||
.processSync(doc)
|
||||
|
@ -427,6 +450,7 @@ async function transormJsonSchema(file: string) {
|
|||
// mermaid project specific plugin
|
||||
originalFilename: file,
|
||||
addAutogeneratedWarning: !noHeader,
|
||||
addEditLink: 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', () => {
|
||||
// TODO Is there a way to test this with --vitepress given as a process argument?
|
||||
|
||||
|
|
Loading…
Reference in New Issue