diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 7a1c491935e..257977e8aba 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -55,6 +55,16 @@ Below is a list of popular documentation tools that you can use to write your do 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` + .. toctree:: :hidden: @@ -62,3 +72,4 @@ Below is a list of popular documentation tools that you can use to write your do /intro/sphinx /intro/docusaurus /intro/markdoc + /intro/mdbook diff --git a/docs/user/intro/mdbook.rst b/docs/user/intro/mdbook.rst new file mode 100644 index 00000000000..8be2ee35cdc --- /dev/null +++ b/docs/user/intro/mdbook.rst @@ -0,0 +1,71 @@ +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 install mdbook + # For an example book.. + # - mdbook init docs + - mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html + +.. _mdBook: https://rust-lang.github.io/mdBook/ + +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 + +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 +--------------------------- + +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/ 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: