Merge pull request #243 from smashwilson/addenda

Addenda

Author: smashwilson

developing/architecture.rst

@@ -68,8 +68,8 @@ When a content consumer initiates an HTTPS request:
 #. :term:`nginx` terminates TLS and, in turn, proxies the request to its linked :term:`presenter`.
 #. The :term:`presenter` queries its content map with the :term:`presented URL` to discover the :term:`content ID` of the content that should be rendered at that path.
 #. Next, the presenter queries the :term:`content service` to acquire the content for that ID. The content service locates the appropriate :term:`metadata envelope`, all site-wide assets, and performs any necessary post-processing.
-#. Armed with the content ID and a layout key from the metadata envelope, the presenter locates the Nunjucks :term:`template` that should be used to decorate the raw content. If no template is routed, this request is skipped and a null layout (that renders the envelope's body directly) is used.
-#. Meanwhile, any "related documents" that are requested by the envelope will be queried from the :term:`content service`.
+#. If any :term:`addenda` are requested by the current envelope, each addenda envelope is fetched from the content service.
+#. The presenter locates the Nunjucks :term:`template` that should be used to decorate the raw content based on a regular expression match on the presented URL. If no template is routed, this request is skipped and a null layout (that renders the envelope's body directly) is used.
 #. The presenter renders the metadata envelope using the layout. The resulting HTML document is returned to the user.
 
 Lifecycle of a Control Repository Update

developing/envelope.rst

@@ -33,6 +33,10 @@ This is an example envelope that demonstrates the full document structure, inclu
       "title": "The previous article",
       "url": "/blog/previous-article"
     },
+    "addenda": {
+      "arbitrary_name": "content-id",
+      "repository_toc": "https://github.com/deconst/deconst-docs/_toc"
+    },
     "asset_offsets": {
       "local/path/image.jpg": [23, 1456],
       "other/asset.gif": [451]
@@ -100,6 +104,9 @@ This is an example envelope that demonstrates the full document structure, inclu
 
     If the ``url`` key is absolute (rooted at the document root, like ``/blog/other-post``), the presenter will re-root it based on the current mapping of the content repository. If it's relative, it will be left as-is.
 
+  addenda
+    Cross-references to related documents that should be fetched along with this envelope to be made available to the template. Each document's envelope is available as ``deconst.addenda.<name>.envelope``. Most likely, the attribute you want is ``deconst.addenda.<name>.envelope.body``.
+
   asset_offsets
     This key must only be present in the intermediate representation used to communicate between a preparer and the submitter. Its keys are local paths to asset files relative to the asset directory. Each value is an array of character offsets into ``body`` that should be replaced by the full, public URL of the asset.
 

writing-docs/coordinator/templates.rst

@@ -15,6 +15,7 @@ There are several special helpers and variables that are made available to each
  * ``{{ deconst.content.envelope.body }}``: This one is very important: it'll be replaced by the actual content of the page.
  * ``{{ deconst.content.envelope.title }}``: The name of the page, if one has been provided.
  * ``{{ deconst.content.envelope.toc }}``: The *local* table of contents for the current page, if one is available.
+ * ``{{ deconst.addenda.<name>.envelope.body }}``: The body of a requested *addenda envelope*. For example, the Sphinx preparer cross references a repository-wide table of contents as ``deconst.addenda.repository_toc.envelope.body``.
  * ``{{{ deconst.assets.js_xyz_url }}}``: The final https CDN URL of the JavaScript asset bundle from the "xyz" subdirectory. See :ref:`the assets section <control-template-assets>` for more details.
  * ``{{{ deconst.assets.css_xyz_url }}}``: The same thing a CSS asset bundle.
  * ``{{{ deconst.assets.image_xyz_jpg_url }}}``: The asset URL for an image asset.