Migrate the docs to a JS based Static Site Generator

[Jwaegebaert]

Currently, we work with Material for MkDocs to generate the documentation site. This requires your device, or docker container, to have Python installed, which isn't the most complex to get working but can get tricky when working with the pipelines. Here the idea would be to move to a single technology stack.

We'll need to research the JavaScript-based alternatives and see which would be more viable for the CLI for M365. Some possible options that could be interesting to research are Nextjs, Gatsby, and Docusaurus.

Jamstack - generators, this is a handy site that you can use to find some SSGs.

Feel free to comment on your experience(s) with any JS-based SSG you've used in the past.
At the moment, I'm looking into the Docusaurus generator 😄

Some criteria points to keep in mind:

• Easy navigation
• Quick navigation to commands
• Layered navigation up to x levels deep.
• Be able to influence the URLs of pages and or create URL aliases for backward compatibility and SEO.
• Version-specific docs
• Breadcrumbs
• Support for tagging pages
• Integrated search engine
• Landing page support
• Table of contents for pages
• Support for tagging pages
• Integration with Google Analytics
• Customizable code fences
• Custom HTML-templates
  • or at least the possibility of extending existing templates.
• Social Media integration (be able to influence how links render)
• Dark mode

[waldekmastykarz]

I like the idea! Using one technology stack will make it easier for us to maintain and set up our docs to meet our needs.

Before we proceed with evaluating different SSGs, I suggest we define evaluation criteria so that we'll be comparing apples with apples.

[garrytrinder]

I don't mind what we use as long as it suits our current and potentially future needs.

Are you able to expand on Proper UI, Easy navigation and Quick navigation to commands. I don't really see these as an issue with the current technology and more of a content issue?

I would also include in the list

• Version specific docs
• Landing page support

[Jwaegebaert]

Are you able to expand on Proper UI, Easy navigation and Quick navigation to commands. I don't really see these as an issue with the current technology and more of a content issue?

Those are indeed not a problem with our current setup, I included those more as criteria to keep in mind when comparing with new tools. 😄

[martinlingstuyl]

What about

• custom HTML-templates
  or at least the possibility for extending existing templates.
• customizable code fences
• Social Media integration (be able to influence how links render)
• be able to influence the URL's of pages and or create URL aliasses for backwards compatibility and SEO.

About navigation I'd say:

• be able to build layered navigation up to x levels deep.
• breadcrumbs

A lot of this should fall in place if we can just use custom templates.
A possible downside is it will also mean having to do more work on the website. We're a bit pampered with what mkdocs-materiel does for us.

[appieschot]

I have some experience with Hugo and am quite happy with that as for docs I agree with most of the topics named above. We should however order or prioritize them as not all of them are evenly important ;-)

[Jwaegebaert]

We should however order or prioritize them as not all of them are evenly important

That's a good idea, should we divide them up in groups or make a priority list with the most important ones at the top?

[Jwaegebaert]

Docusaurus

I've done some research about Docusarus and even went so far as to create a PoC for it. It offers us a lot of flexibility on how we want to build and layout our documentation and is built with high attention to the developer and contributor experience.

These are some of the big features available:

• Built with React:

  • Extend and customize with React
  • Gain full control of your site's browsing experience by providing your own React components

• Pluggable:

  • Bootstrap your site with a basic template, then use advanced features and plugins
  • Open source your plugins to share with the community

• Developer experience:

  • Universal configuration entry point to make it more maintainable by contributors
  • Hot reloading with lightning-fast incremental build-on changes
  • Route-based code and data splitting
  • Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease

• SEO friendly:

  • HTML files are statically generated for every possible path.
  • Page-specific SEO to help your users land on your official docs directly relating to their problems at hand.

• Powered by MDX:

  • Write interactive components via JSX and React embedded in Markdown.
  • Share your code in live editors to get your users to love your products on the spot.

• Search: Your full site is searchable.

• Document Versioning: Helps keep documentation in sync with project releases.

• Internationalization (i18n): Translate your site in multiple locales.

• Lightning-fast. Docusaurus 2 follows the PRPL Pattern that makes sure your content loads blazing fast.

• Accessible. Attention to accessibility, making your site equally accessible to all users.

PoC

Regarding the PoC, an example of our docs is available at https://jwaegebaert.github.io/cli-microsoft365-docusaurus/
I've built it with version 6.1 and the source code is available in the repo https://github.com/Jwaegebaert/cli-microsoft365-docusaurus.

Here are a few things to keep in mind when looking through the PoC.

• The search engine isn't enabled because Algolia DocSearch only offers free versions to live builds. Doc Search - Who can apply?
• The admonition syntax is different from MKDocs so that they won't be rendered properly.
• Same goes for the tabs we use with the command outputs but I've refactored all the Planner commands so be sure to take a peak there. planner bucket add
• Navigation has been modified a bit with landing pages for the categories. planner
• Navigation in mobile view doesn't look super clean yet 😅 same goes for the footer

Looking forward to hearing your thoughts about this 😄
Be sure to also check out the code behind it. https://github.com/Jwaegebaert/cli-microsoft365-docusaurus/tree/master/docs

[Jwaegebaert]

😄 white space is very important for readability and to just prevent from the UI from being crammed. Also, if the body is too broad, the content will become hard to read forcing people either to size the window or move their head like following a tennis (badminton 😄) match.

Good point, it can become more difficult when users read it on bigger screens. I'll see if I can implement some margin on bigger screens as those examples do. It may be subtle but it does make a difference when you're reading long sections 😄

Ps: Love the badminton comparison 😄

[waldekmastykarz]

@milanholemans you can look at it in many ways. Sure, some folks might look at it and say that we don't do everything PowerShell does. On the other hand, what are the odds that you will need everything? If that's the way you're evaluating tech, are you really willing to switch or just looking for reasons to justify your decision not to switch? What if you want to see if the few things you need are there and your only reference point are PowerShell cmdlets? Before we decide to remove it, I'd like us to give it more thought.

[milanholemans]

Before we decide to remove it, I'd like us to give it more thought.

Certainly, I just wanted to share my point of view.

[martinlingstuyl]

Wow, I totally missed this entire conversation 😮
Anyway, great work compiling this @Jwaegebaert! I'm all on board with this.

[arjunumenon]

You share my pain @martinlingstuyl . Guilty as charged on me too.

Amazing work on that @Jwaegebaert . You have done lot of research. Docs on TS. Just Wow!! 🔥🔥.