diff --git a/doc/usage.md b/doc/usage.md
new file mode 100644
index 00000000..caafd099
--- /dev/null
+++ b/doc/usage.md
@@ -0,0 +1,242 @@
+# Usage
+
+To use the {fmt} library, add `fmt/core.h`, `fmt/format.h`, `fmt/format-inl.h`,
+`src/format.cc` and optionally other headers from a [release archive](
+https://github.com/fmtlib/fmt/releases/latest) or the [git repository](
+https://github.com/fmtlib/fmt) to your project. Alternatively, you can
+[build the library with CMake](#building).
+
+## Building the Library {#building}
+
+The included [CMake build
+script](https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt) can be
+used to build the fmt library on a wide range of platforms. CMake is
+freely available for download from .
+
+CMake works by generating native makefiles or project files that can be
+used in the compiler environment of your choice. The typical workflow
+starts with:
+
+ mkdir build # Create a directory to hold the build output.
+ cd build
+ cmake .. # Generate native build scripts.
+
+run in the `fmt` repository.
+
+If you are on a \*nix system, you should now see a Makefile in the
+current directory. Now you can build the library by running
+`make`{.interpreted-text role="command"}.
+
+Once the library has been built you can invoke
+`make test`{.interpreted-text role="command"} to run the tests.
+
+You can control generation of the make `test` target with the `FMT_TEST`
+CMake option. This can be useful if you include fmt as a subdirectory in
+your project but don\'t want to add fmt\'s tests to your `test` target.
+
+If you use Windows and have Visual Studio installed, a
+`FMT.sln` file and several `.vcproj` files will be created. You can
+then build them using Visual Studio or msbuild.
+
+On Mac OS X with Xcode installed, an `.xcodeproj`{.interpreted-text
+role="file"} file will be generated.
+
+To build a [shared
+library](https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries)
+set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
+
+ cmake -DBUILD_SHARED_LIBS=TRUE ..
+
+To build a [static library]{.title-ref} with position independent code
+(required if the main consumer of the fmt library is a shared library
+i.e. a Python extension) set the `CMAKE_POSITION_INDEPENDENT_CODE` CMake
+variable to `TRUE`:
+
+ cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
+
+## Installing the Library
+
+After building the library you can install it on a Unix-like system by
+running `sudo make install`{.interpreted-text role="command"}.
+
+## Usage with CMake
+
+You can add the `fmt` library directory into your project and include it
+in your `CMakeLists.txt` file:
+
+ add_subdirectory(fmt)
+
+or
+
+ add_subdirectory(fmt EXCLUDE_FROM_ALL)
+
+to exclude it from `make`, `make all`, or `cmake --build .`.
+
+You can detect and use an installed version of {fmt} as follows:
+
+ find_package(fmt)
+ target_link_libraries( fmt::fmt)
+
+Setting up your target to use a header-only version of `fmt` is equally
+easy:
+
+ target_link_libraries( PRIVATE fmt::fmt-header-only)
+
+## Usage with build2
+
+You can use [build2](https://build2.org), a dependency manager and a
+build-system combined, to use `fmt`.
+
+Currently this package is available in these package repositories:
+
+- **https://cppget.org/fmt/** for released and published versions.
+- [The git repository with the sources of the build2 package of
+ fmt](https://github.com/build2-packaging/fmt.git) for unreleased or
+ custom revisions of `fmt`.
+
+**Usage:**
+
+- `build2` package name: `fmt`
+- Library target name : `lib{fmt}`
+
+For example, to make your `build2` project depend on `fmt`:
+
+- Add one of the repositories to your configurations, or in your
+ `repositories.manifest`, if not already there:
+
+ :
+ role: prerequisite
+ location: https://pkg.cppget.org/1/stable
+
+- Add this package as a dependency to your `./manifest` file (example
+ for `v7.0.x`):
+
+ depends: fmt ~7.0.0
+
+- Import the target and use it as a prerequisite to your own target
+ using [fmt]{.title-ref} in the appropriate `buildfile`:
+
+ import fmt = fmt%lib{fmt}
+ lib{mylib} : cxx{**} ... $fmt
+
+Then build your project as usual with [b]{.title-ref} or [bdep
+update]{.title-ref}.
+
+For `build2` newcomers or to get more details and use cases, you can
+read the `build2` [toolchain
+introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
+
+## Usage with Meson
+
+[Meson\'s WrapDB
+\]{.title-ref} includes a
+`fmt` package, which repackages fmt to be built by Meson as a
+subproject.
+
+**Usage:**
+
+- Install the `fmt` subproject from the WrapDB by running:
+
+ meson wrap install fmt
+
+ from the root of your project.
+
+- In your project\'s `meson.build` file, add an entry for the new
+ subproject:
+
+ fmt = subproject('fmt')
+ fmt_dep = fmt.get_variable('fmt_dep')
+
+- Include the new dependency object to link with fmt:
+
+ my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep])
+
+**Options:**
+
+If desired, `fmt` may be built as a static library, or as a header-only
+library.
+
+For a static build, use the following subproject definition:
+
+ fmt = subproject('fmt', default_options: 'default_library=static')
+ fmt_dep = fmt.get_variable('fmt_dep')
+
+For the header-only version, use:
+
+ fmt = subproject('fmt')
+ fmt_dep = fmt.get_variable('fmt_header_only_dep')
+
+## Building the Documentation
+
+To build the documentation you need the following software installed on
+your system:
+
+- [Python](https://www.python.org/) with pip and virtualenv
+
+- [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
+
+- [Less](http://lesscss.org/) with `less-plugin-clean-css`. Ubuntu
+ doesn\'t package the `clean-css` plugin so you should use `npm`
+ instead of `apt` to install both `less` and the plugin:
+
+ sudo npm install -g less less-plugin-clean-css.
+
+First generate makefiles or project files using CMake as described in
+the previous section. Then compile the `doc` target/project, for
+example:
+
+ make doc
+
+This will generate the HTML documentation in `doc/html`.
+
+## Conda
+
+fmt can be installed on Linux, macOS and Windows with
+[Conda](https://docs.conda.io/en/latest/), using its
+[conda-forge](https://conda-forge.org)
+[package](https://github.com/conda-forge/fmt-feedstock), as follows:
+
+ conda install -c conda-forge fmt
+
+## Vcpkg
+
+You can download and install fmt using the
+[vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
+
+ git clone https://github.com/Microsoft/vcpkg.git
+ cd vcpkg
+ ./bootstrap-vcpkg.sh
+ ./vcpkg integrate install
+ ./vcpkg install fmt
+
+The fmt port in vcpkg is kept up to date by Microsoft team members and
+community contributors. If the version is out of date, please [create an
+issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg
+repository.
+
+## LHelper
+
+You can download and install fmt using
+[lhelper](https://github.com/franko/lhelper) dependency manager:
+
+ lhelper activate
+ lhelper install fmt
+
+All the recipes for lhelper are kept in the [lhelper\'s
+recipe](https://github.com/franko/lhelper-recipes) repository.
+
+## Android NDK
+
+fmt provides [Android.mk
+file](https://github.com/fmtlib/fmt/blob/master/support/Android.mk) that
+can be used to build the library with [Android
+NDK](https://developer.android.com/tools/sdk/ndk/index.html). For an
+example of using fmt with Android NDK, see the
+[android-ndk-example](https://github.com/fmtlib/android-ndk-example)
+repository.
+
+## Homebrew
+
+fmt can be installed on OS X using [Homebrew](https://brew.sh/):
+
+ brew install fmt
diff --git a/doc/usage.rst b/doc/usage.rst
deleted file mode 100644
index 6d637a2f..00000000
--- a/doc/usage.rst
+++ /dev/null
@@ -1,250 +0,0 @@
-*****
-Usage
-*****
-
-To use the {fmt} library, add :file:`fmt/core.h`, :file:`fmt/format.h`,
-:file:`fmt/format-inl.h`, :file:`src/format.cc` and optionally other headers
-from a `release archive `_ or
-the `Git repository `_ to your project.
-Alternatively, you can :ref:`build the library with CMake `.
-
-.. _building:
-
-Building the Library
-====================
-
-The included `CMake build script`__ can be used to build the fmt
-library on a wide range of platforms. CMake is freely available for
-download from https://www.cmake.org/download/.
-
-__ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt
-
-CMake works by generating native makefiles or project files that can
-be used in the compiler environment of your choice. The typical
-workflow starts with::
-
- mkdir build # Create a directory to hold the build output.
- cd build
- cmake .. # Generate native build scripts.
-
-where :file:`{}` is a path to the ``fmt`` repository.
-
-If you are on a \*nix system, you should now see a Makefile in the
-current directory. Now you can build the library by running :command:`make`.
-
-Once the library has been built you can invoke :command:`make test` to run
-the tests.
-
-You can control generation of the make ``test`` target with the ``FMT_TEST``
-CMake option. This can be useful if you include fmt as a subdirectory in
-your project but don't want to add fmt's tests to your ``test`` target.
-
-If you use Windows and have Visual Studio installed, a :file:`FMT.sln`
-file and several :file:`.vcproj` files will be created. You can then build them
-using Visual Studio or msbuild.
-
-On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated.
-
-To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to
-``TRUE``::
-
- cmake -DBUILD_SHARED_LIBS=TRUE ..
-
-__ https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries
-
-
-To build a `static library` with position independent code (required if the main
-consumer of the fmt library is a shared library i.e. a Python extension) set the
-``CMAKE_POSITION_INDEPENDENT_CODE`` CMake variable to ``TRUE``::
-
- cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
-
-
-Installing the Library
-======================
-
-After building the library you can install it on a Unix-like system by running
-:command:`sudo make install`.
-
-Usage with CMake
-================
-
-You can add the ``fmt`` library directory into your project and include it in
-your ``CMakeLists.txt`` file::
-
- add_subdirectory(fmt)
-
-or
-
-::
-
- add_subdirectory(fmt EXCLUDE_FROM_ALL)
-
-to exclude it from ``make``, ``make all``, or ``cmake --build .``.
-
-You can detect and use an installed version of {fmt} as follows::
-
- find_package(fmt)
- target_link_libraries( fmt::fmt)
-
-Setting up your target to use a header-only version of ``fmt`` is equally easy::
-
- target_link_libraries( PRIVATE fmt::fmt-header-only)
-
-Usage with build2
-=================
-
-You can use `build2 `_, a dependency manager and a
-build-system combined, to use ``fmt``.
-
-Currently this package is available in these package repositories:
-
-- **https://cppget.org/fmt/** for released and published versions.
-- `The git repository with the sources of the build2 package of fmt `_
- for unreleased or custom revisions of ``fmt``.
-
-**Usage:**
-
-- ``build2`` package name: ``fmt``
-- Library target name : ``lib{fmt}``
-
-For example, to make your ``build2`` project depend on ``fmt``:
-
-- Add one of the repositories to your configurations, or in your
- ``repositories.manifest``, if not already there::
-
- :
- role: prerequisite
- location: https://pkg.cppget.org/1/stable
-
-- Add this package as a dependency to your ``./manifest`` file
- (example for ``v7.0.x``)::
-
- depends: fmt ~7.0.0
-
-- Import the target and use it as a prerequisite to your own target
- using `fmt` in the appropriate ``buildfile``::
-
- import fmt = fmt%lib{fmt}
- lib{mylib} : cxx{**} ... $fmt
-
-Then build your project as usual with `b` or `bdep update`.
-
-For ``build2`` newcomers or to get more details and use cases, you can read the
-``build2``
-`toolchain introduction `_.
-
-Usage with Meson
-================
-
-`Meson's WrapDB ` includes a ``fmt``
-package, which repackages fmt to be built by Meson as a subproject.
-
-**Usage:**
-
-- Install the ``fmt`` subproject from the WrapDB by running::
-
- meson wrap install fmt
-
- from the root of your project.
-
-- In your project's ``meson.build`` file, add an entry for the new subproject::
-
- fmt = subproject('fmt')
- fmt_dep = fmt.get_variable('fmt_dep')
-
-- Include the new dependency object to link with fmt::
-
- my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep])
-
-**Options:**
-
-If desired, ``fmt`` may be built as a static library, or as a header-only
-library.
-
-For a static build, use the following subproject definition::
-
- fmt = subproject('fmt', default_options: 'default_library=static')
- fmt_dep = fmt.get_variable('fmt_dep')
-
-For the header-only version, use::
-
- fmt = subproject('fmt')
- fmt_dep = fmt.get_variable('fmt_header_only_dep')
-
-Building the Documentation
-==========================
-
-To build the documentation you need the following software installed on your
-system:
-
-* `Python `_ with pip and virtualenv
-* `Doxygen `_
-* `Less `_ with ``less-plugin-clean-css``.
- Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm``
- instead of ``apt`` to install both ``less`` and the plugin::
-
- sudo npm install -g less less-plugin-clean-css.
-
-First generate makefiles or project files using CMake as described in
-the previous section. Then compile the ``doc`` target/project, for example::
-
- make doc
-
-This will generate the HTML documentation in ``doc/html``.
-
-Conda
-=====
-
-fmt can be installed on Linux, macOS and Windows with
-`Conda `__, using its
-`conda-forge `__
-`package `__, as follows::
-
- conda install -c conda-forge fmt
-
-Vcpkg
-=====
-
-You can download and install fmt using the `vcpkg
-`__ dependency manager::
-
- git clone https://github.com/Microsoft/vcpkg.git
- cd vcpkg
- ./bootstrap-vcpkg.sh
- ./vcpkg integrate install
- ./vcpkg install fmt
-
-The fmt port in vcpkg is kept up to date by Microsoft team members and community
-contributors. If the version is out of date, please `create an issue or pull
-request `__ on the vcpkg repository.
-
-LHelper
-=======
-
-You can download and install fmt using
-`lhelper `__ dependency manager::
-
- lhelper activate
- lhelper install fmt
-
-All the recipes for lhelper are kept in the
-`lhelper's recipe `__ repository.
-
-Android NDK
-===========
-
-fmt provides `Android.mk file`__ that can be used to build the library
-with `Android NDK `_.
-For an example of using fmt with Android NDK, see the
-`android-ndk-example `_
-repository.
-
-__ https://github.com/fmtlib/fmt/blob/master/support/Android.mk
-
-Homebrew
-========
-
-fmt can be installed on OS X using `Homebrew `_::
-
- brew install fmt