diff --git a/docs/source/contributor_release.rst b/docs/source/contributor_release.rst
index ef091bbd6..930cf0bf6 100644
--- a/docs/source/contributor_release.rst
+++ b/docs/source/contributor_release.rst
@@ -3,60 +3,63 @@
 Making a notebook release
 =========================
 
-This document guides a contributor to create a release of the Jupyter
+This document guides a contributor through creating a release of the Jupyter
 notebook.
 
 Check installed tools
 ---------------------
-Review :doc:`Installing Javascript machinery <development_js>`. Make sure all
-the tools needed to generate the minified JavaScript and CSS files are
-properly installed.
+Review :ref:`development_js`. Make sure all the tools needed to generate the
+minified JavaScript and CSS files are properly installed.
 
 Clean the repository
 --------------------
 You can remove all non-tracked files with:
 
-.. code::
+.. code:: bash
 
-    $ git clean -xfdi
+    git clean -xfdi
 
 This would ask you for confirmation before removing all untracked files. Make
 sure the ``dist/`` folder is clean and avoid stale build from
 previous attempts.
 
-Steps to create a release
--------------------------
+Create the release
+------------------
 
-1. Update version number in ``notebook/_version.py``.
+#.  Update version number in ``notebook/_version.py``.
 
-2. Run ``$ python setup.py jsversion``. It will modify (at least)
-``notebook/static/base/js/namespace.js`` to make the notebook version available
-from within JavaScript.
+#.  Run this command:
 
-3 . Commit and tag the release with the current version number:
+    .. code:: bash
 
-.. code::
+        python setup.py jsversion
 
-    git commit -am "release $VERSION"
-    git tag $VERSION
+    It will modify (at least) ``notebook/static/base/js/namespace.js`` which
+    makes the notebook version available from within JavaScript.
 
+#.  Commit and tag the release with the current version number:
 
-4. You are now ready to build the ``sdist`` and ``wheel``:
+    .. code:: bash
 
-.. code::
+        git commit -am "release $VERSION"
+        git tag $VERSION
 
-    $ python setup.py sdist --formats=zip,gztar
-    $ python setup.py bdist_wheel
+#.  You are now ready to build the ``sdist`` and ``wheel``:
 
+    .. code:: bash
 
-5. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
-Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
+        python setup.py sdist --formats=zip,gztar
+        python setup.py bdist_wheel
 
-.. code::
+#.  You can now test the ``wheel`` and the ``sdist`` locally before uploading
+    to PyPI. Make sure to use `twine <https://github.com/pypa/twine>`_ to
+    upload the archives over SSL.
 
-    $ twine upload dist/*
+    .. code:: bash
 
-6. If all went well, change the ``notebook/_version.py`` back adding the ``.dev`` suffix.
+        twine upload dist/*
 
-7. Push directly on master, not forgetting to push ``--tags``.
+#.  If all went well, change the ``notebook/_version.py`` back adding the
+    ``.dev`` suffix.
 
+#.  Push directly on master, not forgetting to push ``--tags`` too.
diff --git a/docs/source/development_js.rst b/docs/source/development_js.rst
index 0d5731502..987b56e4d 100644
--- a/docs/source/development_js.rst
+++ b/docs/source/development_js.rst
@@ -13,13 +13,17 @@ Building the Notebook from its GitHub source code requires some tools to
 create and minify JavaScript components and the CSS. These tools and the
 following steps are used when making a Notebook release.
 
-1. Install `Node.js <https://nodejs.org/>`_ and `npm`.
+#. Install `Node.js <https://nodejs.org/>`_ and `npm`.
 
-   - *Using the installers on Node.js website*: Select a pre-built installer
+   - Using the installers on Node.js website:
+
+     Select a pre-built installer
      on the Node.js website. The installer will include `Node.js` and
      Node's package manager, `npm`.
 
-   - *Using system's package manager*: Install `node.js` and `npm` using the 
+   - Using system's package manager:
+
+     Install `node.js` and `npm` using the
      system's package manager. For example, the command for Ubuntu or Debian
      is:
 
@@ -27,7 +31,7 @@ following steps are used when making a Notebook release.
 
          sudo apt-get install nodejs-legacy npm
 
-2. Build the JavaScript and CSS by running:
+#. Build the JavaScript and CSS by running:
 
    .. code:: bash