Skip to content

Docusaurs: Script the old syntaxes to the new form #4574

@Jwaegebaert

Description

@Jwaegebaert

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:

  • Resolve options with no unique options. Search on the following:
## Options
```
  • Tabs where quadruple backticks occur. e.q. 'project-doctor'
  • Options that don't contain global. e.q. 'project-doctor'
  • (Bug in script) With the upgrade to mdx. Some internal links extension names end with more x chars. Search on mdxx
  • Delete the file _global.md and create under the directory src/docs the file globalOptions.md. Resources below.
  • Update _global.mdx with definition-list code-block
  • Add a new file to the directory src/remark named definitionLists.mjs. Resources below.
  • Install the required packages for the remark plugin npm i [email protected] micromark. Note: validate if dev-dependency is enough
  • Update docusaurus.config.js to include remark plugin. Resources below.

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

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions