Mkdocs are great to use for doucmentation purpose.

why people are drawn to the Mkdocs? Because it requires only md language to make edits and it can be used off internet, and many more beautiful feature that comes with the Mkdocs.

Quick Overview where does Mkdocs fit in?

Here's a quick overview of where MkDocs fits in the broader ecosystem of tools used.

CRM (System of Record) ├─ Dynamics 365 ├─ Salesforce └─ HubSpot

CMS / Docs / Knowledge (System of Knowledge)/Static Site Generators ├─ MkDocs ├─ Docusaurus ├─ GitBook └─ Confluence ├─ Hugo └─ Gatsby

Quick Start

Deploy mkdocs-material to Azure

Easiest tool to build documentation site!

Prerequisites:

• Completed mkdocs project ready for deployment
• An Azure account with an active subscription
• A Github account

Deployment

Fastest way:

1. Go to portal.azure.com

2. Search "Static Web Apps" at the search bar

3. Create a new Statatic Web Apps with the following critical information:

   • Source: GitHub
   • Repository: Select your source code repository from GitHub
   • Branch: pick Main (for now)
   • Build Presets: HTML
   • App Location: "/site/"
   • output Location: "/"

4. Click "Review + create" button. Then click "Create".

5. Wait for the deployment to complete. It may take ~ 10 minutes.

6. To view your web site, click "Go to resource", then click "Visit your site".

!!! note

Don't see the site? Check back later as it may not immediately deploy the site on internet.

How to Update the MKDOCS?

Once the github recognize the main branch, then it will automatically run the steps to automaticlaly host to the web.

Simply, run mkdocs build. Then publish that version in git.

My verdict

Intially, I love mkdocs for its simplicity and ease of use. A couple months later, I revisit the docusaurus then I felt it fits better for my use case.

• The front end is more flexible and customizable with React.
• Its folder structure is more intuitive and easier to navigate.