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