Skip to content

Commit

Permalink
Add mdbook docs page
Browse files Browse the repository at this point in the history
This shows how to host docs with mdbook.

Requires #11848 to not need a reshim
  • Loading branch information
ericholscher committed Dec 11, 2024
1 parent 2830766 commit 29299af
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 0 deletions.
10 changes: 10 additions & 0 deletions docs/user/intro/doctools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`
57 changes: 57 additions & 0 deletions docs/user/intro/mdbook.rst
Original file line number Diff line number Diff line change
@@ -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/

0 comments on commit 29299af

Please sign in to comment.