Markbind: Layouts: give a way to insert default content at top/bottom of the page body

[damithc]

Current: Users can use the layouts feature to configure various defaults for a page e.g., footer, header

Suggested: Give a way to specify some default content to be at the top and bottom of the page body.

Justification: In some cases, the user may want to wrap body content in a div e.g., <div id="main"> or insert a TopNav in every page.

Some options:

1. Support a top.md and bottom.md within a layout
2. Support a page.md within a layout e.g.,

<include src="topNav.md" />
<div id="main">
{{ body }}
<hr>
</div>

The advantage of option 2 is that we can even support default <frontmatter>

[acjh]

If we're going to that extent, then should we just support a layout file similar to Jekyll?

https://jekyllrb.com/docs/step-by-step/04-layouts/

[damithc]

If we're going to that extent, then should we just support a layout file similar to Jekyll?

Yes, this is a move in that direction. We can either go all the way in one step (if that is feasible) or move incrementally.

[crphang]

Hey @damithc, I would like to confirm the differences in the desired behaviour of this issue with the current behaviour of layouts https://markbind.org/userGuide/tweakingThePageStructure.html#page-layouts.

What we currently do is that we only replace header, footer, sitenav that is given by a specified layout created by the user if it is specified in frontmatter.

What we hope to extend here is to have something like a page.md layout, and instead of inserting Header, Footer etc, we invert the relationship and insert the content of the source file within page.md as described by the example Aaron shared: https://jekyllrb.com/docs/step-by-step/04-layouts/

[damithc]

Yes, that's right @Crphang

[crphang]

Wanted to add more on the desired interaction here. The current way we handle layouts is as described here

<frontmatter>
  layout: chapterLayout
  header: header.md
</frontmatter>

By default, we respect user input and always overwrite the header when it is provided. This behaviour needs to be maintained for backward compatibility and user experience.

However, by introducing a "core layout template" page.md we also need to deal with another interaction. Consider this page.md:

<frontmatter>
  header: header.md
</frontmatter>

<div id="main">
{{ body }}
<hr>

Here, page.md references a header file from header folder. So it would be incredibly confusing the user whether we are taking header from actual HEADER_FOLDER_PATH or whether we should use the one referenced in page.md. This confusion would persist even if it is stated in the user guide.

Keeping it extremely simple for now, I propose that page.md cannot reference headers that are outside of the layout folder. This ensures backward compatibility, keeps logic simple for both us and the user.

[damithc]

@Crphang if you have an idea of how you want the feature to work, perhaps you can write the _full_ documentation of the feature first so that we can give feedback based on the full picture? Reason: I'm not yet clear how exactly the authors will use this feature. You can either give it here or create a PR and update the user guide in the PR (preferred).