Skip to content

Commit bf5162f

Browse files
committed
Add mdbook docs page
This shows how to host docs with mdbook. Requires #11848 to not need a reshim
1 parent 1ebd4e5 commit bf5162f

File tree

2 files changed

+67
-0
lines changed

2 files changed

+67
-0
lines changed

docs/user/intro/doctools.rst

+10
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,13 @@ with more coming soon.
4949
:bdg-success:`md`
5050
Written in
5151
:bdg-info:`javascript`
52+
53+
.. grid-item-card:: mdBook
54+
:link: mdbook.html
55+
56+
mdBook is a command line tool to create books with Markdown built in Rust.
57+
58+
Supported formats
59+
:bdg-success:`md`
60+
Written in
61+
:bdg-info:`rust`

docs/user/intro/mdbook.rst

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
mdBook
2+
======
3+
4+
.. meta::
5+
:description lang=en: Learn how to host mdBook documentation on Read the Docs.
6+
7+
`mdBook`_ is a command line tool to create books with Markdown.
8+
9+
Minimal configuration is required to build an existing mdBook project on Read the Docs.
10+
11+
.. code-block:: yaml
12+
:caption: .readthedocs.yaml
13+
14+
version: 2
15+
16+
build:
17+
os: ubuntu-lts-latest
18+
tools:
19+
rust: latest
20+
commands:
21+
- cargo --version
22+
- cargo install mdbook
23+
# For an example book..
24+
# - mdbook init docs
25+
- mdbook build docs --dest-dir $READTHEDOCS_OUTPUT/html
26+
27+
.. _mdBook: https://rust-lang.github.io/mdBook/
28+
29+
Limitations
30+
-----------
31+
32+
All Read the Docs features are supported for mdBook projects,
33+
as it builds static HTML files that can be hosted on Read the Docs.
34+
35+
Getting started
36+
---------------
37+
38+
- If you have an existing mdBook project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
39+
- If you're new to mdBook, check out the official `Getting started with mdBook`_ guide.
40+
41+
.. _Getting started with mdBook: https://rust-lang.github.io/mdBook/guide/creating.html
42+
43+
Example repository and demo
44+
---------------------------
45+
46+
Example repository
47+
https://github.com/readthedocs/test-builds/tree/mdbook
48+
49+
Demo
50+
https://test-builds.readthedocs.io/en/mdbook/
51+
52+
Further reading
53+
---------------
54+
55+
* `mdBook documentation`_
56+
57+
.. _mdBook documentation: https://rust-lang.github.io/mdBook/

0 commit comments

Comments
 (0)