Update MkDocs page to be generic and note MkDocs for Material integra…

…tion (#11871)

This is trying to clarify support for the tooling,
and note which parts are generic to MkDocs.

Refs squidfunk/mkdocs-material#7822

<!-- readthedocs-preview docs start -->
---
:books: Documentation previews :books:

- User's documentation (`docs`):
https://docs--11871.org.readthedocs.build/en/11871/

<!-- readthedocs-preview docs end -->

<!-- readthedocs-preview dev start -->
- Developer's documentation (`dev`):
https://dev--11871.org.readthedocs.build/en/11871/

<!-- readthedocs-preview dev end -->

docs/user/index.rst

@@ -6,11 +6,10 @@ Read the Docs: documentation simplified
    :hidden:
    :caption: Getting started
 
-   /tutorial/index
+   Tutorial </tutorial/index>
    /intro/add-project
    /intro/doctools
    /examples
-   /intro/accounts
 
 .. toctree::
    :maxdepth: 2
@@ -20,6 +19,7 @@ Read the Docs: documentation simplified
    /config-file/index
    /config-file/v2
    /addons
+   /intro/accounts
    /automation-rules
    /guides/reproducible-builds
 

docs/user/intro/doctools.rst

@@ -68,8 +68,8 @@ Below is a list of popular documentation tools that you can use to write your do
 .. toctree::
    :hidden:
 
-   /intro/mkdocs
    /intro/sphinx
+   /intro/mkdocs
    /intro/docusaurus
    /intro/markdoc
    /intro/mdbook

docs/user/intro/mkdocs.rst

@@ -1,62 +1,66 @@
-.. _material:
-
-Material for MkDocs
-===================
+MkDocs
+======
 
 .. meta::
-   :description lang=en: Hosting Material for MkDocs sites on Read the Docs.
+   :description lang=en: Hosting MkDocs sites on Read the Docs.
 
 `MkDocs`_ is a fast, simple static site generator that's geared towards building project documentation.
-`Material for MkDocs`_ is a powerful documentation framework on top of MkDocs.
 Mkdocs is written in Python, and supports documentation written in Markdown.
+When using MkDocs, we recommend using the `Material for MkDocs`_ theme,
+and this guide is mostly focused on the integration required to make it work well on Read the Docs.
 
-.. note::
-
-    This page is explicitly about Material for MkDocs. We're working on a guide for plain MkDocs as well.
-
-Minimal configuration required to build an existing Material for MkDocs project on Read the Docs looks like this,
-specifying a python toolchain on Ubuntu, defining the location of the installation requirements, and using the built-in
-:ref:`mkdocs <config-file/v2:mkdocs>` command:
+Minimal configuration is required to build an existing MkDocs project on Read the Docs:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
 
     version: 2
 
     build:
-      os: ubuntu-24.04
+      os: "ubuntu-24.04"
       tools:
         python: "3"
-
-    python:
-      install:
-        - requirements: requirements.txt
+      # We recommend using a requirements file for reproducible builds.
+      # This is just a quick example to get started.
+      # https://docs.readthedocs.io/page/guides/reproducible-builds.html
+      jobs:
+        pre_install:
+          - pip install mkdocs-material
 
     mkdocs:
       configuration: mkdocs.yml
 
 .. _MkDocs: https://www.mkdocs.org/
 .. _Material for MkDocs: https://squidfunk.github.io/mkdocs-material
 
+Configuring Material for MkDocs on Read the Docs
+------------------------------------------------
 
-Quick start
------------
+In order to use the Material for MkDocs theme on Read the Docs,
+you need to install and configure it.
+In your `mkdocs.yml` file, set the theme to `material`:
 
-- If you have an existing Material for MkDocs project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+.. code-block:: yaml
+   :caption: mkdocs.yml
 
-- If you're new to Material for MkDocs, check out the official `Getting started with Material for MkDocs`_ guide.
+    theme:
+      name: material
 
-.. _Getting started with Material for MkDocs: https://squidfunk.github.io/mkdocs-material/getting-started/
+With these changes, your MkDocs project will use the Material for MkDocs theme when built on Read the Docs,
+and should work with the configuration file shown above.
 
-Configuring Material for MkDocs and Read the Docs addons
---------------------------------------------------------
+Quick start
+-----------
 
-For optimal integration with Read the Docs, make the optional following configuration changes to your Material for MkDocs config.
+- You can use our :ref:`MkDocs example project <examples:mkdocs>` as a reference to create a new MkDocs project.
+- If you have an existing MkDocs project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+- If you're new to MkDocs, check out the official `Getting Started <https://www.mkdocs.org/getting-started/>`_ guide.
 
-.. contents::
-   :depth: 1
-   :local:
-   :backlinks: none
+Configuring MkDocs and Read the Docs Addons
+-------------------------------------------
+
+There are some additional steps you can take to configure your MkDocs project to work better with Read the Docs,
+and these apply to all MkDocs projects.
 
 Set the canonical URL
 ~~~~~~~~~~~~~~~~~~~~~
@@ -74,6 +78,15 @@ Set your MkDocs `site URL`_  to your Read the Docs canonical URL using a
 
 .. _Site URL: https://www.mkdocs.org/user-guide/configuration/#site_url
 
+Configuring Material for MkDocs and Read the Docs Addons
+--------------------------------------------------------
+
+`Material for MkDocs`_ is a powerful documentation theme on top of MkDocs.
+The following steps are specific to integrating Material for MkDocs and Read the Docs.
+
+.. contents::
+   :local:
+   :backlinks: none
 
 Configure Read the Docs search
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/user/tutorials/index.rst

@@ -30,15 +30,3 @@ Tutorials
 ⏩️ :doc:`/examples`
   If you are bootstrapping a new documentation project,
   here is a list of example projects that you can derive your setup from.
-
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   /tutorial/index
-   /intro/sphinx
-   /intro/mkdocs
-   /intro/add-project
-   /config-file/index
-   /examples