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).