Docusaurs: Adjust `--help` print to accommodate different syntaxes

[Jwaegebaert]

Because our syntaxes will change for certain markdown elements, our code to print the --help output needs to be adjusted for this change.

Changed syntaxes:

• [ ] Admonitions
• [ ] Code tabs
• [ ] Global option embeds
• [ ] Definition-lists

Note!

When making a PR for this issue, make sure you target the branch docs-migration.

---

Related to #4396

[Jwaegebaert]

This PR is on-hold to start with until we have a clear view of what all the adjusted syntaxes are. Related to: #4574

[Jwaegebaert]

New syntaxes to keep in mind:

All file extension names are changes from md to mdx

Change extension names at src/cli/Cli.ts lines 683, 687, 690

Remove FrontMatter occurrences. e.g. login.mdx

In src/utils/md.ts

function removeFrontmatter(md: string): string {
  return md.replace(/^---[\s\S]*?---/gm, '').trim();
}

Remove imports

In src/utils/md.ts

function removeImports(md: string): string {
  return md.replace(/^import .+;$/gms, '').trim();
}

Remove tab tags in outputs. e.g. plan-add.mdx

In src/utils/md.ts update the method convertContentTabs

!!! Change the order in convertFunctions that convertCodeFences happens first and then convertContentTabs

function convertContentTabs(md: string): string {
  return md
    .replace(/<TabItem value="([^"]+)">/gm, '$1')
    .replace(/.*<\/?(Tabs|TabItem)>.*\n?/g, '')
    .replace(/```(?:\w+)?\s*([\s\S]*?)\s*```/g, '$1')
    .trim();
}

Remove definition-list code-blocks

Already done thanks to the function convertCodeFences in the file src/utils/md.ts

Make sure <Global /> and <CLISettings /> are rendered correctly

In src/utils/md.ts update the method includeContent

function includeContent(md: string, rootFolder: string): string {
  const mdxImports = [
    { tag: "<Global />", location: "docs/cmd/_global.mdx" },
    { tag: "<CLISettings />", location: "docs/_clisettings.mdx" }
  ];

  mdxImports.forEach(mdxImport => {
    md = md.replace(mdxImport.tag, () => {
      return fs.readFileSync(path.join(rootFolder, mdxImport.location), 'utf8');
    }).replace(/(```\r\n)\r\n(```md defintion-list\r\n)/g, "$1$2");
  });

  return md;
}

Change the admonitions with the new syntax

In src/utils/md.ts update the method convertAdmonitions

function convertAdmonitions(md: string): string {
  const regex = new RegExp(/^:::(\w+)([\s\S]*?):::$/, 'gm');
  return md.replace(regex, (_, label: string, content: string) => label.toLocaleUpperCase() + EOL + EOL + content.trim());
}

[Jwaegebaert]

@pnp/cli-for-microsoft-365-maintainers I've updated the help output to accommodate the changes made by Docusaurus.

I've created a diffchecker link that provides a quick overview how this change will look like. https://www.diffchecker.com/VgO6k3Uu The left is our current output with MKDocs and on the right we have the new output based from Docusaurus

[Adam-it]

too me it looks pretty much the same 👍 awesome work @Jwaegebaert 👍 you rock 🤩