Merge pull request #4640 from aloisklink/docs/fix-edit-url
Fix the "Edit this page on GitHub" link in Vitepress documentation for the Mermaid Config pages
This commit is contained in:
commit
1b2340ba75
|
@ -30,11 +30,20 @@
|
||||||
* @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
|
* @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
|
||||||
* it.)
|
* it.)
|
||||||
*/
|
*/
|
||||||
|
// @ts-ignore: we're importing internal jsonschema2md functions
|
||||||
|
import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
|
||||||
|
// @ts-ignore: we're importing internal jsonschema2md functions
|
||||||
|
import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
|
||||||
|
// @ts-ignore: we're importing internal jsonschema2md functions
|
||||||
|
import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
|
||||||
|
// @ts-ignore: we're importing internal jsonschema2md functions
|
||||||
|
import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
|
||||||
import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync } from 'fs';
|
import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync } from 'fs';
|
||||||
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 { dump, load, JSON_SCHEMA } from 'js-yaml';
|
||||||
|
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 +218,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 +242,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 +282,27 @@ 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);
|
||||||
|
yamlFrontMatter.value = dump({
|
||||||
|
...(load(yamlFrontMatter.value, { schema: JSON_SCHEMA }) as
|
||||||
|
| Record<string, unknown>
|
||||||
|
| undefined),
|
||||||
|
editLink: `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 +339,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)
|
||||||
|
@ -323,16 +357,6 @@ const transformMarkdown = (file: string) => {
|
||||||
copyTransformedContents(file, !verifyOnly, formatted);
|
copyTransformedContents(file, !verifyOnly, formatted);
|
||||||
};
|
};
|
||||||
|
|
||||||
import { load, JSON_SCHEMA } from 'js-yaml';
|
|
||||||
// @ts-ignore: we're importing internal jsonschema2md functions
|
|
||||||
import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
|
|
||||||
// @ts-ignore: we're importing internal jsonschema2md functions
|
|
||||||
import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
|
|
||||||
// @ts-ignore: we're importing internal jsonschema2md functions
|
|
||||||
import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
|
|
||||||
// @ts-ignore: we're importing internal jsonschema2md functions
|
|
||||||
import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Transforms the given JSON Schema into Markdown documentation
|
* Transforms the given JSON Schema into Markdown documentation
|
||||||
*/
|
*/
|
||||||
|
@ -420,16 +444,18 @@ async function transormJsonSchema(file: string) {
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
const transformed = remark()
|
const transformer = remark()
|
||||||
.use(remarkGfm)
|
.use(remarkGfm)
|
||||||
.use(remarkFrontmatter, ['yaml']) // support YAML front-matter in Markdown
|
.use(remarkFrontmatter, ['yaml']) // support YAML front-matter in Markdown
|
||||||
.use(transformMarkdownAst, {
|
.use(transformMarkdownAst, {
|
||||||
// mermaid project specific plugin
|
// mermaid project specific plugin
|
||||||
originalFilename: file,
|
originalFilename: file,
|
||||||
addAutogeneratedWarning: !noHeader,
|
addAutogeneratedWarning: !noHeader,
|
||||||
|
addEditLink: noHeader,
|
||||||
removeYAML: !noHeader,
|
removeYAML: !noHeader,
|
||||||
})
|
});
|
||||||
.stringify(markdownAst as Root);
|
|
||||||
|
const transformed = transformer.stringify(await transformer.run(markdownAst as Root));
|
||||||
|
|
||||||
const formatted = prettier.format(transformed, {
|
const formatted = prettier.format(transformed, {
|
||||||
parser: 'markdown',
|
parser: 'markdown',
|
||||||
|
|
|
@ -105,6 +105,29 @@ 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?
|
||||||
|
|
||||||
|
|
|
@ -35,7 +35,12 @@ export default defineConfig({
|
||||||
themeConfig: {
|
themeConfig: {
|
||||||
nav: nav(),
|
nav: nav(),
|
||||||
editLink: {
|
editLink: {
|
||||||
pattern: 'https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/src/docs/:path',
|
pattern: ({ filePath, frontmatter }) => {
|
||||||
|
if (typeof frontmatter.editLink === 'string') {
|
||||||
|
return frontmatter.editLink;
|
||||||
|
}
|
||||||
|
return `https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/src/docs/${filePath}`;
|
||||||
|
},
|
||||||
text: 'Edit this page on GitHub',
|
text: 'Edit this page on GitHub',
|
||||||
},
|
},
|
||||||
sidebar: {
|
sidebar: {
|
||||||
|
|
Loading…
Reference in New Issue