deconst · smashwilson · May 26, 2015 · May 21, 2015 · May 26, 2015 · May 26, 2015
diff --git a/_images/travis-account-menu.png b/_images/travis-account-menu.png
diff --git a/_images/travis-enable-build.png b/_images/travis-enable-build.png
diff --git a/_images/travis-envvars.png b/_images/travis-envvars.png
diff --git a/running/architecture.rst b/running/architecture.rst
@@ -13,6 +13,7 @@ Terminology
 .. glossary::
 
   content repository
+  content repositories
     Location containing material to be included as a subset of the completed site. Often, the
     material within will be written in a friendlier human-editable markup format such as
     reStructuredText or Markdown.

diff --git a/writing-docs/author.rst b/writing-docs/author.rst
diff --git a/writing-docs/author/index.rst b/writing-docs/author/index.rst
@@ -0,0 +1,41 @@
+Authoring Content for Deconst
+=============================
+
+Deconst *content authors* write the documentation that's rendered at some domain and path on the final instance. The content that makes up a deconst instance is brought together from many :term:`content repositories`, each of which contributes a single logical unit of documentation that can be maintained independently from all of the others.
+
+The domain and subpath that host the content from a specific content repository is determined by a mapping that's managed within the :term:`control repository` associated with your Deconst instance. To add a new content repository to the instance, you or a *site coordinator* will need to add an entry to the control repository's :ref:`content mapping file <control-map>`.
+
+Once the content repository is fully configured, any changes merged into the "master" branch will automatically be live.
+
+Where Will Your Content Live
+----------------------------
+
+The final output from each content repository will be presented at a subpath of the complete site. For example, if you create the following pages:
+
+.. code-block:: text
+
+  welcome
+  chapter-1/introduction
+  chapter-1/getting-started
+  chapter-2/more-advanced
+
+And you're currently mapped to the ``books/example/`` subpath of *mysite.com* by the control repository, then your pages will be available at the following URLs:
+
+.. code-block:: text
+
+  https://mysite.com/books/example/welcome
+  https://mysite.com/books/example/chapter-1/introduction
+  https://mysite.com/books/example/chapter-1/getting-started
+  https://mysite.com/books/example/chapter-2/more-advanced
+
+As you work, you can freely create new pages and directories and they will automatically be available within that subpath.
+
+Supported Content Repository Formats
+------------------------------------
+
+Each content repository can independently choose a documentation engine that makes the most sense for the content it contains. You can choose from any format that has a matching :term:`preparer`. Preparers extend the native documentation engine to support additional functionality that Deconst needs to integrate their output with the rest of the system.
+
+.. toctree::
+
+  sphinx
+  jekyll
diff --git a/writing-docs/author/jekyll.rst b/writing-docs/author/jekyll.rst
@@ -0,0 +1,96 @@
+Markdown content in Jekyll
+==========================
+
+`Jekyll <http://jekyllrb.com/>`_ is a static site engine that's specialized for blog authoring. Although Jekyll can support content in many markup formats, it's most commonly used to render `markdown <http://daringfireball.net/projects/markdown/>`_.
+
+Specifying a Layout
+-------------------
+
+Deconst allows each page to be assocated with :ref:`a layout <control-layout>` from the control repository by specifying a *key*. If a page names a Jekyll layout in its frontmatter, that layout name will also be used as its layout key for deconst. If you wish to use different keys for the Jekyll build, specify a ``deconst_layout`` key instead.
+
+Frontmatter
+-----------
+
+Certain frontmatter keys have meaning to both Jekyll and Deconst. These include:
+
+ * ``title`` will be made available to site layouts as ``{{{ metadata.title }}}``. Usually, this will be used within an ``<h1>`` element on the page and as the browser title.
+ * ``categories`` is a YAML list of strings used to manually identify related content. These are meant to be chosen by hand from a small, fixed list of possibilities. Site layouts should generally render categories rather than tags.
+ * ``tags`` is another YAML list of strings. These are more ad-hoc, but may be manipulated by the content service. Additional tags may be appended by latent semantic indexing or normalization processes.
+ * ``author`` should be set to the name of a blog post's author.
+ * ``bio`` may be set to a short paragraph introducing the author.
+ * ``date`` is used to specify the publish date of a blog post in **YYYY-mm-dd HH:MM:SS** format.
+ * ``disqus`` is a subdictionary used to control the inclusion of a Disqus comment field, if supported by the layout. It should have two subkeys: ``short_name``, as provided by your Disqus account, and ``mode``, which may be either ``count`` or ``embed`` to control the Disqus script injected into this page.
+
+All of these are optional and only have meaning if the equivalent metadata attributes are used in the page's Deconst layout.
+
+Assets
+------
+
+To properly include images or other static assets in your Jekyll content, use the `jekyll-assets plugin <http://jekyll-assets.github.io/jekyll-assets/>`_. The Jekyll preparer will hook the assets plugin and override it to properly submit assets to the content service.
+
+ 1. Add an ``_assets/images`` directory to your Jekyll repository. Place any image assets that you reference within this directory.
+ 2. Reference images within a post or a page with the ``asset_path`` Liquid tag.
+
+With Markdown:
+
+.. code-block:: text
+
+  [alt text]({% asset_path image-path.png %})
+
+Or with raw HTML:
+
+.. code-block:: html
+
+  <img src="{% asset_path image-path.png %}" alt="alt text">
+
+Plugins and Dependencies
+------------------------
+
+If you use Jekyll plugins that rely on other gems, you'll need to add a ``Gemfile`` to the root directory of your content repository to declare your dependencies.
+
+It isn't necessary to list either jekyll or jekyll-assets as explicit dependencies, because the preparer already includes them. If you do include them, the versions you declare will be ignored during preparation, anyway. It won't harm the build to do so, though.
+
+.. code-block:: ruby
+
+  source 'https://rubygems.org'
+
+  gem 'stringex'
+
+Be sure to run ``bundle install`` to generate an equivalent ``Gemfile.lock``, to ensure that the versions of your dependencies are consistent from build to build.
+
+Continuous Deployment
+---------------------
+
+To configure the continuous deployment process for your content repository, place a file called ``.travis.yml`` with the following contents at the root of your repository.
+
+.. code-block:: yaml
+
+  ---
+  language: ruby
+  ruby:
+  - "2.2.0"
+  install:
+  - git clone https://github.com/deconst/preparer-jekyll.git /tmp/preparer-jekyll
+  - cd /tmp/preparer-jekyll && rake install
+  script:
+  - deconst-preparer-jekyll
+
+Now, visit `Travis <https://travis-ci.org/>`_ and choose "Accounts" from the drop-down menu in the upper right:
+
+.. image:: /_images/travis-account-menu.png
+
+On the accounts page, locate the GitHub organization and repository for your content repository, and toggle the box to activate the integration:
+
+.. image:: /_images/travis-enable-build.png
+
+Next, click on the gear icon to navigate to the build's configuration, and set the following environment variables:
+
+* ``CONTENT_ID_BASE`` is the common prefix that will be used to produce :term:`content IDs` for the rendered content. Set this to the URL of your GitHub repository.
+* ``CONTENT_STORE_URL`` is the URL of the content store that the prepare should target. Consult with your site administrators for this value.
+* ``CONTENT_STORE_APIKEY`` is an API key issued by the content store for your repository. Ask a site administrator to generate one of these for you.
+
+.. image:: /_images/travis-envvars.png
+
+.. note::
+
+  Eventually, this will be configured for you automatically as soon as your content repository is mapped. For now, you'll need to do it by hand.
diff --git a/writing-docs/author/sphinx.rst b/writing-docs/author/sphinx.rst
@@ -0,0 +1,71 @@
+reStructuredText content in Sphinx
+==================================
+
+`Sphinx <http://sphinx-doc.org/contents.html>`_ is a documentation builder that assembles `reStructureText <http://docutils.sourceforge.net/rst.html>`_ source files into cohesive output that includes tables of contents, cross-references, and integrated navigation.
+
+Specifying a Layout
+-------------------
+
+Deconst allows each page to be assocated with :ref:`a layout <control-layout>` from the control repository by specifying a *key*. Sphinx doesn't include the concept of applying a layout to an individual page. The Sphinx preparer works around this by recognizing a piece of `per-page metadata <http://sphinx-doc.org/markup/misc.html#file-wide-metadata>`_ in each file.
+
+You can see which layouts are available within your instance by consulting :ref:`layout mapping files within the control repository. <control-layout>` To support a consistent experience across an entire deconst instance, you should coordinate your choice of layout with your instance's information architects.
+
+To use a specific layout for a page, include the following as the *first line* of any ``.rst`` file:
+
+.. code-block:: rst
+
+  :deconstlayout: this-pages-layout-key
+
+If most of the pages in your repository will be using a common layout, you can also specify a default layout key by adding the following to your ``conf.py`` file:
+
+.. code-block:: python
+
+  deconst_default_layout = "this-repos-default-layout-key"
+
+Assets
+------
+
+To integrate properly with Deconst's asset pipeline:
+
+ 1. Place any images in an `_images` directory at the top level of your Sphinx documentation.
+ 2. Reference images in ``.rst`` files by including a ``.. image`` macro.
+
+.. code-block:: rst
+
+  .. image:: /_images/deconst-initial.png
+
+Continuous Deployment
+---------------------
+
+To configure the continuous deployment process for your content repository, place a file called ``.travis.yml`` with the following contents at the root of your repository.
+
+.. code-block:: yaml
+
+  ---
+  language: python
+  python:
+  - "3.4"
+  install:
+  - "pip install -e git+https://github.com/deconst/preparer-sphinx.git#egg=deconstrst"
+  script:
+  - deconst-preparer-sphinx
+
+Now, visit `Travis <https://travis-ci.org/>`_ and choose "Accounts" from the drop-down menu in the upper right:
+
+.. image:: /_images/travis-account-menu.png
+
+On the accounts page, locate the GitHub organization and repository for your content repository, and toggle the box to activate the integration:
+
+.. image:: /_images/travis-enable-build.png
+
+Next, click on the gear icon to navigate to the build's configuration, and set the following environment variables:
+
+* ``CONTENT_ID_BASE`` is the common prefix that will be used to produce :term:`content IDs` for the rendered content. Set this to the URL of your GitHub repository.
+* ``CONTENT_STORE_URL`` is the URL of the content store that the prepare should target. Consult with your site administrators for this value.
+* ``CONTENT_STORE_APIKEY`` is an API key issued by the content store for your repository. Ask a site administrator to generate one of these for you.
+
+.. image:: /_images/travis-envvars.png
+
+.. note::
+
+  Eventually, this will be configured for you automatically as soon as your content repository is mapped. For now, you'll need to do it by hand.
diff --git a/writing-docs/control-advanced.rst → ...ing-docs/coordinator/control-advanced.rst b/writing-docs/control-advanced.rst → ...ing-docs/coordinator/control-advanced.rst
diff --git a/writing-docs/coordinator.rst → writing-docs/coordinator/index.rst b/writing-docs/coordinator.rst → writing-docs/coordinator/index.rst
diff --git a/writing-docs/layout-assets.rst → writing-docs/coordinator/layout-assets.rst b/writing-docs/layout-assets.rst → writing-docs/coordinator/layout-assets.rst
diff --git a/writing-docs/layouts.rst → writing-docs/coordinator/layouts.rst b/writing-docs/layouts.rst → writing-docs/coordinator/layouts.rst
diff --git a/writing-docs/mapping.rst → writing-docs/coordinator/mapping.rst b/writing-docs/mapping.rst → writing-docs/coordinator/mapping.rst
diff --git a/writing-docs/index.rst b/writing-docs/index.rst
@@ -8,5 +8,5 @@ If you want to manage or produce content that's published as part of a deconst s
 
 .. toctree::
 
-  author
-  coordinator
+  author/index
+  coordinator/index