From ce422c154276b3b6b2e5886b20eac77629183677 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 9 Jan 2025 08:59:40 -0800 Subject: [PATCH] Update MkDocs page to be generic and note MkDocs for Material integration (#11871) This is trying to clarify support for the tooling, and note which parts are generic to MkDocs. Refs https://github.com/squidfunk/mkdocs-material/issues/7822 --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--11871.org.readthedocs.build/en/11871/ - Developer's documentation (`dev`): https://dev--11871.org.readthedocs.build/en/11871/ --- docs/user/index.rst | 4 +- docs/user/intro/doctools.rst | 2 +- docs/user/intro/mkdocs.rst | 73 +++++++++++++++++++++-------------- docs/user/tutorials/index.rst | 12 ------ 4 files changed, 46 insertions(+), 45 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 8688a89b0df..9fe10f07cc7 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -6,11 +6,10 @@ Read the Docs: documentation simplified :hidden: :caption: Getting started - /tutorial/index + Tutorial /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 diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 257977e8aba..7247395c28a 100644 --- a/docs/user/intro/doctools.rst +++ b/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 diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index 8d087f67319..0e4b92f371e 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -1,22 +1,15 @@ -.. _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 ` command: +Minimal configuration is required to build an existing MkDocs project on Read the Docs: .. code-block:: yaml :caption: .readthedocs.yaml @@ -24,13 +17,15 @@ specifying a python toolchain on Ubuntu, defining the location of the installati 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 @@ -38,25 +33,34 @@ specifying a python toolchain on Ubuntu, defining the location of the installati .. _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 ` 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 `_ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst index c66dd7bc097..8cb2becfe36 100644 --- a/docs/user/tutorials/index.rst +++ b/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