diff --git a/README.md b/README.md
index a66a5659..62c6fab5 100644
--- a/README.md
+++ b/README.md
@@ -154,52 +154,6 @@ Roadmap
 See [the roadmap](ROADMAP.md) for the current plan. Help on any of
 these points is welcome!
 
-FAQ
----
-
-### Why do many Jbuilder projects contain a Makefile?
-
-Many Jbuilder project contain a toplevel `Makefile`. It is often only
-there for convenience, for the following reasons:
-
-1. there are many different build systems out there, all with a
-   different CLI. If you have been hacking for a long time, the one
-   true invocation you know is `make && make install`, possibly
-   preceded by `./configure`
-
-2. you often have a few common operations that are not part of the
-   build and `make <blah>` is a good way to provide them
-
-3. `make` is shorter to type than `jbuilder build @install`
-
-### How to add a configure step to a jbuilder project?
-
-[example/sample-projects/with-configure-step](example/sample-projects/with-configure-step) shows
-one way to do it which preserves composability; i.e. it doesn't require manually
-running `./configure` script when working on multiple projects at the same time.
-
-### Can I use topkg with jbuilder?
-
-Yes, have a look at the [topkg-jbuilder][topkg-jbuilder] project for
-more details.
-
-### Where can I find some examples of projects using Jbuilder?
-
-The [dune-universe](https://github.com/dune-universe/dune-universe)
-repository contains a snapshot of the latest versions of all opam packages
-depending on jbuilder.  It is therefore a useful reference to search through
-to find different approaches to constructing build rules.
-
-Known issues
-------------
-
-### mli only modules
-
-These are supported, however using them might cause make it impossible
-for non-jbuilder users to use your library. We tried to use them for
-some internal module generated by Jbuilder and it broke the build of
-projects not using Jbuilder:
-
 https://github.com/ocaml/dune/issues/567
 
 So, while they are supported, you should be careful where you use
diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 00000000..13e1c007
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,40 @@
+***
+FAQ
+***
+
+Why do many Jbuilder projects contain a Makefile?
+=================================================
+
+Many Jbuilder project contain a toplevel `Makefile`. It is often only there for
+convenience, for the following reasons:
+
+1. there are many different build systems out there, all with a different CLI.
+   If you have been hacking for a long time, the one true invocation you know is
+   `make && make install`, possibly preceded by `./configure`
+
+2. you often have a few common operations that are not part of the build and
+   `make <blah>` is a good way to provide them
+
+3. `make` is shorter to type than `jbuilder build @install`
+
+How to add a configure step to a jbuilder project?
+==================================================
+
+[example/sample-projects/with-configure-step](example/sample-projects/with-configure-step)
+shows one way to do it which preserves composability; i.e. it doesn't require
+manually running `./configure` script when working on multiple projects at the
+same time.
+
+Can I use topkg with jbuilder?
+==============================
+
+Yes, have a look at the [topkg-jbuilder][topkg-jbuilder] project for
+more details.
+
+here can I find some examples of projects using Jbuilder?
+=========================================================
+
+The [dune-universe](https://github.com/dune-universe/dune-universe) repository
+contains a snapshot of the latest versions of all opam packages depending on
+jbuilder. It is therefore a useful reference to search through to find different
+approaches to constructing build rules.
diff --git a/doc/index.rst b/doc/index.rst
index c7605de5..a847743f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,3 +19,5 @@ Welcome to jbuilder's documentation!
    api-doc
    usage
    advanced-topics
+   faq
+   known-issues
diff --git a/doc/known-issues.rst b/doc/known-issues.rst
new file mode 100644
index 00000000..d02a9655
--- /dev/null
+++ b/doc/known-issues.rst
@@ -0,0 +1,17 @@
+************
+Known Issues
+************
+
+mli only modules
+================
+
+These are supported, however using them might cause make it impossible for
+non-jbuilder users to use your library. We tried to use them for some internal
+module generated by Jbuilder and it broke the build of projects not using
+Jbuilder:
+
+https://github.com/ocaml/dune/issues/567
+
+So, while they are supported, you should be careful where you use them. Using a
+`.ml` only module is still preferable.
+