Writing a Preparer

If you want to include content from a new content repository format, you’ll need to create a new preparer. Generally, a preparer needs to:

  1. Parse the markup language, configuration files, and other metadata for some content format. When possible, you should use the format’s native libraries and tooling to do so.

  2. Parse the _deconst.json file. Consult the new content repository section for its schema.

  3. Copy assets (usually images) to the directory specified by the environment variable ASSET_DIR. It’s best to preserve as much of the local directory structure as possible from the source repository, unless two assets in different subdirectories have the same filename.

  4. Use the markup to produce rendered HTML. The preparer should use a single-character placeholder for each asset URL. As it does so, it should generate a map that associates the path of each asset relative to ASSET_DIR to a collection of character offsets within the body text at which that asset is referenced.

    As a rule, the rendered HTML should omit any layouts from the content repository itself and only render the page content, unadorned. In Deconst, templates will be applied later, from the control repository. This is important to ensure a consistent look and feel across many content repositories published to the same site, as well as allowing users to take advantage of presenter-implemented features like search.

  5. Assemble the content into one or more metadata envelopes that match the envelope schema. If any assets were referenced, include the asset offset map as the asset_offsets element. Write each completed envelope to the directory specified by the environment variable ENVELOPE_DIR as a file with the filename pattern <content ID, URL-encoded>.json.

Docker Container Protocol

If you run your preparer in an independent environment (like a non-Deconst continuous integration server), anything that implements the process above will work fine. If you want your preparer to work within the Deconst client or to be available to automatically created Strider builds, you need to package your preparer in a Docker container image that obeys the container protocol described here.

Deconst preparer containers should respect the following configuration values:

  • ASSET_DIR: The preparer must copy assets to this directory tree.
  • ENVELOPE_DIR: The preparer must write completed envelopes to this directory.
  • CONTENT_ID_BASE: (optional) If set, this should override the content ID base specified in _deconst.json for this preparation run, preferably with some kind of message if they differ.
  • CONTENT_ROOT: (optional) If specified, the preparer should prepare content mounted to a volume at this path within the container. Otherwise, it should default to preparing /usr/content-repo.

When run with no arguments, the preparer container should prepare the content as described above, then exit with an exit status of 0 if preparation was successful, or nonzero if it was not.