We are migrating our documentation from MKDocs to Docusaurus, but the syntax used by MKDocs differs from that used by Docusaurus, making migration challenging. To automate the formatting process, we need a script that can identify and modify all relevant syntax in our documentation files. This issue involves creating and testing the script on our existing documentation to ensure it works correctly and saves time and effort.
Automated tasks
Manual to-do list:
Resources
definitionLists.mjs
import visit from 'unist-util-visit'; // "unist-util-visit": "^2.0.3"
import { micromark } from 'micromark'; // "micromark": "^3.1.0"
/**
* Turns a "```md defintion-list" code block into a definition list
*/
export default function plugin() {
const transformer = (root) => {
visit(root, 'code', (node, index, parent) => {
if (!node.meta?.includes('defintion-list')) {
return;
}
const {value} = node;
const listItems = value.split('\n').filter(x => x);
const items = listItems.map((listItem, i) => {
const content = micromark(i % 2 ? listItem.substring(2, listItem.length) : listItem);
if (i % 2) {
return `<dd>${content}</dd>`;
}
else {
return `<dt>${content}</dt>`;
}
});
parent.children[index] = {
type: 'html',
value: `<dl>${items.join('')}</dl>`
};
});
};
return transformer;
}
docusaurus.config.js
// ...
const config = {
// ...
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
routeBasePath: '/',
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/pnp/cli-microsoft365/blob/main/docs',
showLastUpdateTime: true,
remarkPlugins: []
},
blog: false,
theme: {
customCss: require.resolve('./src/css/custom.css'),
}
})
]
],
// ...
};
async function createConfig() {
const definitionLists = (await import('./src/remark/definitionLists.mjs')).default;
config.presets[0][1].docs.remarkPlugins.push(definitionLists);
return config;
}
module.exports = createConfig;
Related to #4396
We are migrating our documentation from MKDocs to Docusaurus, but the syntax used by MKDocs differs from that used by Docusaurus, making migration challenging. To automate the formatting process, we need a script that can identify and modify all relevant syntax in our documentation files. This issue involves creating and testing the script on our existing documentation to ensure it works correctly and saves time and effort.
Automated tasks
Manual to-do list:
xchars. Search onmdxxDelete the file_global.mdand create under the directorysrc/docsthe fileglobalOptions.md. Resources below._global.mdxwith definition-list code-blocksrc/remarknameddefinitionLists.mjs. Resources below.npm i [email protected] micromark. Note: validate if dev-dependency is enoughdocusaurus.config.jsto include remark plugin. Resources below.Resources
definitionLists.mjs
docusaurus.config.js
Related to #4396