Documentation Cleanup: Update mkdocs.yml

[candidexmedia]

Hi @knadh !

I've been revisiting my previous comments (1, 2) about documentation vs guides vs tutorials, and looking over the docs for this project. I'd like to discuss some suggestions and improvements if you're interested.

Menu Navigation

My first PR touches on the menu navigation. At the moment, the doc's primary menu looks like one long list:

This makes navigating and finding information difficult, especially as the number of pages grows larger. In contrast, here's how Umami Analytics and NocoDB organize their side menu:

As such, I've added some indentation to group certain menu items under a common title and create a second level.

I've also added the following to make the second-level items collapsible:

theme:
  features:
    - navigation.expand

Next Steps

Down the road, I would love to assist with a content audit of the docs to make them more user-friendly, and fill in some blanks. Here are some suggestions:

Proposed Menu Taxonomy (click ▶️ to expand)

Getting Started

• Introduction
• Installation
• Configuration
• Upgrade
• Login
• Concepts

Basics

• Set up SMTP
• Manage Subscription Lists
• Design Campaigns
• Embed Forms
• Generate Archives
• Analyze Reports

Advanced

• Querying and segmenting subscribers
• Templating
• Integrating with external systems
• Bounce processing
• Messengers
• Internationalization

API

• API / Subscribers
• API / Lists
• API / Import
• API / Campaigns
• API / Media
• API / Templates
• API / Transactional

Guides

• Deploying Listmonk with Railway
• Deploying Listmonk with Pikapods
• Deploying Listmonk with Amazon
• Deploying Listmonk with docker and caddy
• Deploying Listmonk on your PC
• Deploying Listmonk with Linux
• Deploying Listmonk with Fly.io

Contribute

• Developer setup
• Report Bugs
• Help with Documentation
• Translate
• Donate

Content Audit

Looking over the docs to make the content easier to understand for both beginners and power users. This includes deciding:

• where content could be rephrased, moved to another section, or expanded upon on its own page
• what info is missing (ex: explaining that users need to find and provide their own SMTPs)
• where to offer additional guidance, and when to link out (ie: designing campaigns for all platforms and what to watch out for)

Guides / Tutorials

There is currently a Tutorials section at the bottom of the Installation page, but this isn't the most ideal area for this kind of content, neither does it take advantage of video embedding capabilities. Some guides may be repetitive and could be grouped by platform.

I'm thinking of two potential ways of managing this, but I'm not sure which way is best:

Option 1 - Umami Approach

Umami has a section at the end of their docs which contains a page for each platform option.

A dedicated page is great for detailing all the idiosyncrasies of each platform when it comes to installing, upgrading, additional external tutorials, etc., rather than making the dedicated Installation, Upgrading, etc. pages longer. This is also great for SEO.

ex: As a Railway user, I want to add additional info for fellow users on how to maintain their Listmonk deployment, and make sure that it doesn't confuse people who use other platforms.

That said, it does create a number of additional pages and menu items.

Option 2 - NocoDB Approach

Rather than create a page for each platform, NocoDB has opted to cover the details of installation for every platform using tabs and collapsible content:

As such, if you're looking for upgrade instructions, the Upgrade page will have details for every single platform, without having to find the singular page for just that platform.

The downside is that the general purpose Installation / Upgrade / etc. pages may become too long.

[knadh]

Thanks @candidexmedia. Looks good. I'll review this locally and get back in a couple of days.

[knadh]

$ mkdocs --version
mkdocs, version 1.5.3 from ~/mkdocs (Python 3.12)

Getting this:

@ (/tmp/listmonk-1/docs/docs) ● patch-1
$ mkdocs serve
Error: MkDocs encountered an error parsing the configuration file: while parsing a block mapping
  in "/tmp/listmonk-1/docs/docs/mkdocs.yml", line 55, column 5
expected <block end>, but found '-'
  in "/tmp/listmonk-1/docs/docs/mkdocs.yml", line 56, column 5

[candidexmedia]

$ mkdocs --version
mkdocs, version 1.5.3 from ~/mkdocs (Python 3.12)

Getting this:

@ (/tmp/listmonk-1/docs/docs) ● patch-1
$ mkdocs serve
Error: MkDocs encountered an error parsing the configuration file: while parsing a block mapping
  in "/tmp/listmonk-1/docs/docs/mkdocs.yml", line 55, column 5
expected <block end>, but found '-'
  in "/tmp/listmonk-1/docs/docs/mkdocs.yml", line 56, column 5

I'll admit: I'm not an expert on Mkdocs 😅 Glad you were able to resolve it with 9adc5e7

[candidexmedia]

Bookmarking the Loops documentation site as inspiration:

Menu: