creating synthetic pages with a plugin

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

creating synthetic pages with a plugin

Jonathan Dowland
Hi folks, relatively new Awestruct user here. I'm using awestruct as part of a (currently private) software project to manage the documentation. The software project has a number of components ("images") for which I want to auto-generate documentation pages. Each "image" is described by a YAML file in the software project file tree. There are also other, static/not-auto-generated pages of documentation as well. The docs and awestruct config, layouts etc. are in a sub-folder "docs" of the main software project.

What I want to achieve is to create new Page objects in awestruct that do not correspond to static files in the documentation tree. If I did have static files, they would basically be stubs like this

title: some-image
layout: image

(My first cut did have exactly this, a bunch of stub files sprinkled around ./doc/*)

The docs/_layout/image.html.slim file is mostly embedded asciidoc. Bits are turned on/off depending on values within the current page object.  My plugin populates the page object with more data for this template to use (by reading in the YAML files from the software project tree. The precise YAML file to read is determined from the title in the front-matter.).

In my plugin, I've tried to create new Awestruct Page objects by hand but I haven't managed to get the rendering/handlers right. For a working solution the closest I've come is to add a dummy file dummy.adoc to the ./docs tree which is a stub as above. Awestruct therefore creates a proper Page object for that, and in my plugin's execute routine I find it, clone it for each of my synthetic pages and change the parameters. This mostly works, but there a lot of caveats (especially when running/refreshing a preview) and it's very ugly.

How should I go about creating a new Page object? I think the key is probably relating to the handler parameter for the Page constructor. I don't know what handler(s) I need nor how to chain them together.

To recap, the pages I want are content-free stubs, pure front data only, that use a slim layout, which is almost entirely asciidoc, but itself happens to be encapsulated within another layout (another slim file), and that finally within yet another slim layout.

Thanks in advance for any advice!

Jonathan Dowland