Content overrides - Githubissues

daveaglick commented 5 years ago

Most of the themes follow a convention for partials like _Head.cshtml but that could quickly become less widespread when new and community themes are created. Instead we need a way for the use of certain overrides to be intrinsic to the build regardless of theme. Shortcodes give us the power of a lightweight templating engine, so I’m thinking we bake in support for overrides like _Head.html, run them through the Shortcode module, then use one of the HTML modules to inject them at the right place. Might even be able to come up with a convention to make this really flexible by specifying where to inject the override inside the override (as frontmatter?).

daveaglick commented 5 years ago

Been thinking about this more and I think it’ll work really well:

Overrides are designated by a double underscore file name prefix and should always have an HTML extension: __foo.html
They are configured by front matter
Front matter contains an HTML query selector of where to apply the override
Front matter optionally contains a position (replace, append, insert after, etc.) - need to figure out the default
Overrides apply to all documents with destination paths in or under the same relative folder as the override
Front matter optionally contains an additional filter (could be based on globing, but that would require a new module that can filter input documents based on globing their destination paths - which would make a cool module)
Shortcodes are applied to the override before insertion (and maybe again to the whole document after all insertions? Or should final shortcode eval wait until after overrides in general?)

daveaglick commented 4 years ago

Going to work on this soon, happy to see the original design from almost a year ago is still pretty relevant. Here's some clarifications:

No special file naming like underscores are needed, as with archives, overrides will be identified by the presence of particular metadata
Override files should be loaded (but not processed/rendered) by a separate pipeline
They should apply to both content and archive pipelines (and any other pipeline that renders content) - to ensure this, the override logic should be placed in the RenderPostProcessTemplates module right after the templates (but before things like MirrorResources and ResolveXrefs).
- Essentially, a new ProcessContentOverrides module should be created and called inside the RenderPostProcessTemplates
The content of the override will be rendered through all templates for all documents that match the target path pattern and have matching elements with the metadata from the original document so that the override can use it (I.e., set an active item in a navigation bar)
Any <head> content will be merged with the original document, whatever is in the <body> is what will replace/modify the elements from the query selector
Uses the following settings:
- OverriddenElements: query selector, all matching elements will be replaced/modified/appended/etc.
- OverridePosition: replace, append, insert after, etc.
- OverridenSources: globbing pattern(s) to filter the override to, if omitted overrides apply to all documents with destination paths in or under the same relative folder as the override

statiqdev / Statiq.Web

Content overrides #832