From bf5162f7f80eb13b81331a28bbd7aa4011c5de34 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 11 Dec 2024 15:08:12 -0800 Subject: [PATCH 1/5] Add mdbook docs page This shows how to host docs with mdbook. Requires https://github.com/readthedocs/readthedocs.org/pull/11848 to not need a reshim --- docs/user/intro/doctools.rst | 10 +++++++ docs/user/intro/mdbook.rst | 57 ++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 docs/user/intro/mdbook.rst diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 6d70d7b9378..cda8aab7474 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -49,3 +49,13 @@ with more coming soon. :bdg-success:`md` Written in :bdg-info:`javascript` + + .. grid-item-card:: mdBook + :link: mdbook.html + + mdBook is a command line tool to create books with Markdown built in Rust. + + Supported formats + :bdg-success:`md` + Written in + :bdg-info:`rust` diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst new file mode 100644 index 00000000000..d226c823f1b --- /dev/null +++ b/docs/user/intro/mdbook.rst @@ -0,0 +1,57 @@ +mdBook +====== + +.. meta:: + :description lang=en: Learn how to host mdBook documentation on Read the Docs. + +`mdBook`_ is a command line tool to create books with Markdown. + +Minimal configuration is required to build an existing mdBook project on Read the Docs. + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + build: + os: ubuntu-lts-latest + tools: + rust: latest + commands: + - cargo --version + - cargo install mdbook + # For an example book.. + # - mdbook init docs + - mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html + +.. _mdBook: https://rust-lang.github.io/mdBook/ + +Limitations +----------- + +All Read the Docs features are supported for mdBook projects, +as it builds static HTML files that can be hosted on Read the Docs. + +Getting started +--------------- + +- If you have an existing mdBook project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide. +- If you're new to mdBook, check out the official `Getting started with mdBook`_ guide. + +.. _Getting started with mdBook: https://rust-lang.github.io/mdBook/guide/creating.html + +Example repository and demo +--------------------------- + +Example repository + https://github.com/readthedocs/test-builds/tree/mdbook + +Demo + https://test-builds.readthedocs.io/en/mdbook/ + +Further reading +--------------- + +* `mdBook documentation`_ + +.. _mdBook documentation: https://rust-lang.github.io/mdBook/ From 97790946c38ebf347f0d686e5f3b2fce933d930e Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 12 Dec 2024 16:01:57 -0800 Subject: [PATCH 2/5] Update docs/user/intro/mdbook.rst Co-authored-by: Manuel Kaufmann --- docs/user/intro/mdbook.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst index d226c823f1b..e81a6fa23da 100644 --- a/docs/user/intro/mdbook.rst +++ b/docs/user/intro/mdbook.rst @@ -18,7 +18,6 @@ Minimal configuration is required to build an existing mdBook project on Read th tools: rust: latest commands: - - cargo --version - cargo install mdbook # For an example book.. # - mdbook init docs From 9d63e24dd947a388938ea06b7935e56141edef9c Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 12 Dec 2024 16:05:55 -0800 Subject: [PATCH 3/5] Add back to toctree --- docs/user/intro/doctools.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 12a03713294..a9711ebd556 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -67,3 +67,4 @@ with more coming soon. /intro/sphinx /intro/docusaurus /intro/markdoc + /intro/mdbook From cb5f63fca99459b86afa034cd2d4cf3c6b7d7dfa Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 16 Dec 2024 15:18:59 -0800 Subject: [PATCH 4/5] Remove Limitations --- docs/user/intro/mdbook.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst index e81a6fa23da..8892ba99c74 100644 --- a/docs/user/intro/mdbook.rst +++ b/docs/user/intro/mdbook.rst @@ -25,12 +25,6 @@ Minimal configuration is required to build an existing mdBook project on Read th .. _mdBook: https://rust-lang.github.io/mdBook/ -Limitations ------------ - -All Read the Docs features are supported for mdBook projects, -as it builds static HTML files that can be hosted on Read the Docs. - Getting started --------------- From c59f5c2b3c8af4719b82f4acef910fa69dfdab25 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 16 Dec 2024 15:27:03 -0800 Subject: [PATCH 5/5] Note additional-css --- docs/user/intro/mdbook.rst | 21 +++++++++++++++++++++ docs/user/intro/mkdocs.rst | 3 ++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst index 8892ba99c74..8be2ee35cdc 100644 --- a/docs/user/intro/mdbook.rst +++ b/docs/user/intro/mdbook.rst @@ -33,6 +33,27 @@ Getting started .. _Getting started with mdBook: https://rust-lang.github.io/mdBook/guide/creating.html +Configuring mdBook and Read the Docs Addons +------------------------------------------- + +Adjust the flyout menu font size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add a ``readthedocs.css`` to your build with the `additional-css `_ flag, +so that the font in the :ref:`flyout-menu:Addons flyout menu` matches the theme better. + +.. code-block:: css + :caption: readthedocs.css: + + :root { + /* Increase the font size of the flyout menu */ + --readthedocs-flyout-font-size: 1.3rem; + + /* Increase the font size of the notifications */ + --readthedocs-notification-font-size: 1.3rem; + + } + Example repository and demo --------------------------- diff --git a/docs/user/intro/mkdocs.rst b/docs/user/intro/mkdocs.rst index ed357507899..8d087f67319 100644 --- a/docs/user/intro/mkdocs.rst +++ b/docs/user/intro/mkdocs.rst @@ -161,7 +161,8 @@ To integrate the :ref:`flyout-menu:Addons flyout menu` version menu into your si Adjust the flyout menu font size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Edit ``readthedocs.css`` to so that the font in the :ref:`flyout-menu:Addons flyout menu` matches the theme better. +Add a ``readthedocs.css`` to your build, +so that the font in the :ref:`flyout-menu:Addons flyout menu` matches the theme better. .. code-block:: css :caption: readthedocs.css: