docs-virtdata.docsys.design.templating._md Maven / Gradle / Ivy

Go to download
## Templating Design

- Static files which use standard extensions should be loadable without
  triggering any render logic. This is important to make static content
  load efficiently, such as themes, javascript libraries, etc.
- Markdown sections should be editable inside html templates. This is important to allow markdown users to contribute fluidly to the docs without requiring logs of HTML micro-management.
- Markdown should be able to make use of templating. This is important to
  provide an intermediate and simple structural format that can be used
  to drive high level changes in templates.
- Target files should be able to be wrapped automatically with a template
  that is provided by their current directory.
_ Target files should be able to be wrapped automatically with a template
  that is provided by the parent directory of the current directory.
- Rendering stages which are completed should be cached in memory,
  as long as the underlying templates and data have not changed.

## Template File Names

All files which are intended to be interpreted as a template must have an
extension which starts with an underscore. For examples, both `myfile._md` and `myfile._html` would both be considered templates subject to
further processing. This convention is enforced by configuration of the
rendering layers, so that the user can be presented with a logical view
of content which does not include all the template level elements.

### Sources and Targets

All files which can be templated must have a specific source and target
template extension. 

Take for example, an html template file foobarbaz:

The _source extension_ is `._html`. The file `foobarbaz._html` is the _source template_.

The _target extension_ is `.html`. The file `foobarbaz.html` 
 is the _target file_. 
 
The mapping from the _source extension_ to the _target extension_ is the
key to configuring rendering layers. Each rendering layer is configured
with this mapping along with a renderer which can transform file content
from the _source template_ form to the _target file_ content.

### Renderer Configuration

The configuration described above is known as as an `extension mapping`. An extension mapping is meaningless without a way to transform the template into a file, thus a proper rendering configuration consists of the following:

- A source extension.
- A target extension.
- A renderer which can create a virtual file from a template.

If you have multiple extension mappings which chain together, such as `._md -> .md (mustache)` and `.md -> .html (markdown)`, then these will
cascade together gracefully.

## Rendering Steps

Normally, users do not access the template files directly. Ideally, users
are not even aware that there is templating happening at all.

These steps are followed when a user accesses a target file:

1. If the logical name exists on the physical file system, it is provided as-is. This means that for templating to work, the corresponding target file for a given source template must not physically exist on the file system.
2. if the target file does not exist, but a template file for it does, then:
    1. If the file has already been rendered and the source modification time hasn't changed, the the cached copy is provided.
    2. Otherwise, the target file is rendered to a _rendered file_, cached in memory, and also returned to the caller as a virtual file.  

## Rendering Context

If the results of a template were always the same, then the templates would serve no special purpose. When a template is used to render a file, it needs some data to plug in to the template sections.

This data is provided in every case by a basic lazily constructed object model. This is called the TargetPathView. This is called the _source context_ for any rendered file.

The TargetPathView provides access to a few types of data:

- The target path itself.
- Breadcrumbs from the target path up to the filesystem root. (this is the internal virtual file system, and logically limited to the configured paths.)
- Semantic models of the target path, such as contained topics and categories.
- Support for internal rendering helpers, like rendering markdown inside html templates.

The combination of a specific rendering context and template is called
a _rendering scope_, thus a rendering scope has a version which is
the newest version of either components.
 
## Compositing

Composite templates are templates which can automatically layer together
in order to impose a format around target file rendering.

When two templates are composited together, they are set in a parent-child
relationship. As with templates, the context objects for these templates
are also set in a parent-child relationship.

This is the arrangement of a set of composite scopes in chain form:

```
+-------+ parent of -> +-------+ parent of -> +-------+
| tmpl1 |              | tmpl2 |              | tmpl3 |
+-------+              +-------+              +-------+
| view1 |              | view2 |              | view3 |
+-------+  <- child of +-------+  <- child of +-------+
``` 

In this arrangement, tmpl1 is the parent template of templ2, which is the parent of tmpl3. The rendering contexts have the identical arrangement.

When a parent template needs to access the direct child context, it does
so by using the name `inner`

#### Local Directory Template

If you have a template in a directory which has a base name of `_` (underscore) with the same extension as an active source template, then the source template will automatically be promoted to a composite template before it is rendered. 

For example, if you have two files in a directory: `foobarbaz._md` and `_._md`, then the latter file becomes a template that wraps the former.
The contents of the `_._.md` template will wrap **any** other `*._md` template in this directory.

Within the local directory template, the context object is set to a TargetPathView as usual, but an additional element is present which provides access ot the target file under the name `target`.

Within the `foobarbaz._md` template, everything works as it usually does, 
only its placement within the local directory template is determined by
the use of the `target` value.

## Hierarchic Wrapping

Moving from the target file up through the file system, if there are any
templates with the name `__._.md`, then these template are applied just
as above, but they apply for all elements, and they are applied recursively.

Taking the local directory template above into consideration with the 
parent directory template, it is possible to have both apply. ...

## Directory Wrapping

As with any system which can have internal references, it is possible
to create a cyclic dependency. For example, as directory template
which provides a topic list must read the contents of all files which
it will be composited with. This creates a cyclic reference. 
Presently, this is not supported. It is conceptually possible to
make a compositor which can read metadata like topics from rendered
partials without invoking the canonical name of the current target
in rendering, but this will be an incremental improvement.