alternate approach to dynamic templating

[karthik2804]

This PR replaces the approach in https://github.com/fermyon/bartholomew/pull/162.

Instead of specifying configuration in config/site.toml, this approach relies on creating files with a new optional field in the frontmatter (body_source). This approach is cleaner in that there is a file for every document that wants to use dynamic content from another document and does not pollute the configuration file.

An example of using this would be having two content files doc-a.md and doc-b.md where only doc-a has some content.

/content/bartholomew/doc-a.md

title = "This is document A"
template = "template_a"
date = "2022-03-14T00:22:56Z"

---

This is some content contained in document A

/content/bartholomew/doc-b.md

title = "This is document B"
template = "template_b"
date = "2022-03-14T00:22:56Z"
body_source = "/bartholomew/doc-b"

---

Now doc-b would be rendered using the template template_b and content from doc-a.

Additionally, it potentially opens up the option to explore options for remote content sources such as mentioned in https://github.com/fermyon/bartholomew/issues/76

I would like to hear some thoughts on this replacement.

[itowlson]

I am a bit lost by this, I'm afraid, so cannot offer any thoughts. Perhaps a more realistic concrete example would help clarify how this would be used, and how users would change their existing content? I see from the linked issue that our interest is in choosing different sidebars for pages with common body content but I'm struggling to relate that back to your example. Sorry.

(Also if this is a breaking change or merely "now there are two ways of doing the thing.")

[tpmccallum]

Just drawing this out to try and help in the shared understanding.

Where the 3 pages on the left of the diagram would render the content from the single page on the right of the diagram. With the key functionality being that a user stays on the xxxx_main template whilst browsing (instead of being whisked off to common_main). I think I understand this.

[karthik2804]

@itowlson. It would technically be a breaking change but we could always make it "merely two ways" of doing the same thing. And also @tpmccallum is correct in the diagram but with a small change that the common page is not required. The body could be in one of the three pages and shared across them.

[itowlson]

Thanks @tpmccallum - that's super helpful. I see what's going on now.

I'm not familiar with the constraints of Bartholomew syntax but the fact that all these things look "page like" but with special selection rules is a bit confusing to me. Like spin/contributing-docs looks like a page, but can't contain any content because common/contributing-docs supplies its content. My first thought was "would an include directive in the body be more obvious" but I bet that runs into issues with merging page TOCs etc. - it makes sense that only works at page level.

(The previous paragraph is not a request for changes. It's me working through 'why it works this way' in my head.)

I guess my main suggestion, after all that, is that we call it content_source instead of dynamic_content_source (dynamic doesn't seem to be adding anything here, and there's no runtime selection of content, it's locked in at authoring time).

Thank you both for your patient explanations!

[karthik2804]

Ohh that name change makes a lot of sense @itowlson. I will make the changes. The idea of an include directive sounds interesting. I will look into it and see how that plays out and see if I can get it to work.

Just thinking out loud. It could be a shortcode but then rhai scripts would need access to the file system and read and parse the files which might complicate things a little bit. Maybe that can be a future feature potentially?

[itowlson]

Just thinking out loud. ['include'] could be a shortcode but then rhai scripts would need access to the file system and read and parse the files which might complicate things a little bit. Maybe that can be a future feature potentially?

Definitely. That paragraph of rambling was very much me reasoning things out to myself and was not a request for changes.

[tpmccallum]

Added a checklist of changes required in the developer docs issue at https://github.com/fermyon/developer/issues/651

[karthik2804]

@itowlson fixed the name change and also the "not found" handling. Not entirely sure how to write the test for it.

[tpmccallum]

Hi @karthik2804 It seems that some of the blocking comments are outdated perhaps due to new additions in your code. I will re-request a review from @itowlson as you have asked a question Re: writing tests. Can I go ahead and test this now, in terms of functionality with a view to approve and let you cut a new release?

[karthik2804]

Yes it should be good for it.