diff --git a/README.rst b/README.rst
index d56355a39b..fb4bfde88a 100644
--- a/README.rst
+++ b/README.rst
@@ -184,8 +184,13 @@ The top level of a deliverable file is a mapping with keys:
   The slug name of the launchpad project, suitable for use in URLs.
 
 ``release-notes``
-  The URL to the published release notes for the deliverable for the
-  series.
+  The URL or URLs to the published release notes for the deliverable
+  for the series.
+
+  Deliverables contained a single repository should simply include the
+  URL to the notes for that repository. Deliverables made up of
+  multiple repositories should use a hash to map each repository name
+  to its notes URL.
 
 ``send-announcements-to``
   A string containing one or more email addresses to receive
@@ -277,22 +282,26 @@ and then for the subsequent release it would be updated to contain::
 
 For deliverables with multiple repositories, the list of projects
 would contain all of them. For example, the Neutron deliverable might
-be described by ``deliverables/liberty/neutron.yaml`` containing:
+be described by ``deliverables/mitaka/neutron.yaml`` containing:
 
 ::
 
    ---
    launchpad: neutron
    send-announcements-to: openstack-announce@lists.openstack.org
-   release-notes: http://docs.openstack.org/releasenotes/neutron/liberty.html
+   release-notes:
+     openstack/neutron: http://docs.openstack.org/releasenotes/neutron/mitaka.html
+     openstack/neutron-lbaas: http://docs.openstack.org/releasenotes/neutron-lbaas/mitaka.html
+     openstack/neutron-fwaas: http://docs.openstack.org/releasenotes/neutron-fwaas/mitaka.html
+     openstack/neutron-vpnaas: http://docs.openstack.org/releasenotes/neutron-vpnaas/mitaka.html
    releases:
-     - version: 7.0.0
-       projects:
-         - repo: openstack/neutron
-           hash: somethingunique
-         - repo: openstack/neutron-fwaas
-           hash: somethingunique
-         - repo: openstack/neutron-lbaas
-           hash: somethingunique
-         - repo: openstack/neutron-vpnaas
-           hash: somethingunique
+    - version: 8.0.0
+      projects:
+        - repo: openstack/neutron
+          hash: 3213eb124e40b130e174ac3a91067e2b196788dd
+        - repo: openstack/neutron-fwaas
+          hash: ab5622891e2b1a7631f97471f55ffb9b5235e5ee
+        - repo: openstack/neutron-lbaas
+          hash: 19b18f05037dae4bbbada848aae6421da18ab490
+        - repo: openstack/neutron-vpnaas
+          hash: a1b12601a64a2359b2224fd4406c5db008484700
diff --git a/deliverables/mitaka/neutron.yaml b/deliverables/mitaka/neutron.yaml
index b4adf37836..2e00c18eb3 100644
--- a/deliverables/mitaka/neutron.yaml
+++ b/deliverables/mitaka/neutron.yaml
@@ -1,7 +1,11 @@
 ---
 launchpad: neutron
 send-announcements-to: openstack-announce@lists.openstack.org
-release-notes: http://docs.openstack.org/releasenotes/neutron/mitaka.html
+release-notes:
+  openstack/neutron: http://docs.openstack.org/releasenotes/neutron/mitaka.html
+  openstack/neutron-lbaas: http://docs.openstack.org/releasenotes/neutron-lbaas/mitaka.html
+  openstack/neutron-fwaas: http://docs.openstack.org/releasenotes/neutron-fwaas/mitaka.html
+  openstack/neutron-vpnaas: http://docs.openstack.org/releasenotes/neutron-vpnaas/mitaka.html
 releases:
   - version: 8.0.0.0b1
     projects:
diff --git a/openstack_releases/sphinxext.py b/openstack_releases/sphinxext.py
index 604469a990..7142d70a13 100644
--- a/openstack_releases/sphinxext.py
+++ b/openstack_releases/sphinxext.py
@@ -45,7 +45,15 @@ def _list_table(add, headers, data, title='', columns=None):
     for row in data:
         add('   - * %s' % row[0])
         for r in row[1:]:
-            add('     * %s' % r)
+            lines = str(r).splitlines()
+            if not lines:
+                # empty string
+                add('     * ')
+            else:
+                # potentially multi-line string
+                add('     * %s' % lines[0])
+                for l in lines[1:]:
+                    add('       %s' % l)
     add('')
 
 
@@ -212,10 +220,15 @@ class DeliverableDirectiveBase(rst.Directive):
                 'version', 'unreleased')
             ref = ':ref:`%s-%s`' % (series, deliverable_name)
             release_notes = deliverable_info.get('release-notes')
-            if release_notes:
-                notes_link = '`release notes <%s>`__' % release_notes
-            else:
+            if not release_notes:
                 notes_link = ''
+            elif isinstance(release_notes, dict):
+                notes_link = '\n'.join(
+                    '| `%s release notes <%s>`__' % (n.split('/')[-1], v)
+                    for n, v in sorted(release_notes.items())
+                )
+            else:
+                notes_link = '`release notes <%s>`__' % release_notes
             most_recent.append((ref, earliest_version, recent_version, notes_link))
         _list_table(
             lambda t: result.append(t, source_name),
@@ -246,9 +259,18 @@ class DeliverableDirectiveBase(rst.Directive):
             app.info('[deliverables] rendering %s' % deliverable_name)
 
             release_notes = deliverable_info.get('release-notes')
-            if release_notes:
+            if not release_notes:
+                notes_link = None
+            elif isinstance(release_notes, dict):
+                notes_link = ' | '.join(
+                    '`%s <%s>`__' % (n.split('/')[-1], v)
+                    for n, v in sorted(release_notes.items())
+                )
+            else:
+                notes_link = '`%s <%s>`__' % (deliverable_name, release_notes)
+            if notes_link:
                 _add('')
-                _add('Release Notes: %s' % release_notes)
+                _add('Release Notes: %s' % notes_link)
                 _add('')
             link_mode = deliverable_info.get('artifact-link-mode', 'tarball')
             _list_table(