Framework Structure

This is where we tell our tooling how to do what. The _configs/ directory usually contains at least one build\*.yml file that instructs a build routine as well as an asciidoctor.yml file for establishing global AsciiDoc/Asciidoctor settings, and optionally a jekyll.yml file to stand in as the _config.yml for Jekyll operations.

Where we store small-data files.

This directory is for storing templates used in preprocessing.

A directory created and written to during the build process.

This is where most of our content will come from.

The defining file for book builds and the homepage and something of a map for site builds. This file sould have index in its filename but should also be descriptive of what it produces.

Snippets and partials go in here. This is where we put highly reusable and often partly dynamic text content. Snippets should not have headers. They may be collected into files by type or subject, distinguished by AsciiDoc include tags in their comments.

Topics are chunks of content that could stand alone, for instance as a web page, but that also might be reused in different contexts, including as a component of a larger page or other document, such as a book. All topic files should have a level-one header (=).

A freely named directory for your main content, however organized. Often called pages/ to comport with Jekyll conventions.

Files for defining layout and style for publishing go here. Not to be confused with _layouts/, which holds similarly purposeful files for structuring content in preprocess operations.