RFC: Allow the Blade view to be set in Markdown page front matter

[caendesilva]

Summary

This proposal adds a front matter option for Markdown pages to allow a custom Blade template to be used.

Usage

---
extends: my-custom-layout
---

# Markdown content here

Lorem Ipsum Dolor Sit Amet.

Implementation

Implementation is simple by adding the following method override to the MarkdownPage class.

This makes the change fully backwards compatible as it null coalesces to the default behaviour.

public function getBladeView(): string
{
    return $this->matter->get('extends') ?? parent::getBladeView();
}

Alternate implementations

I initially went with extends as the front matter key, as that matches the Blade syntax. I also see that Jigsaw uses extends. However Jekyll uses layout. We could also support both, same as we support both group and category for navigation data.

My thoughts on the matter

Something like this was considered when originally creating HydePHP as I did not find it necessary, and it risks adding complexity without value. Additionally, for most sites this is not needed as the various page types have different views that get automatically configured, and an override could make things less obvious.

Furthermore, the general use of HydePHP means that it's okay that most Markdown-based pages look the same in terms of layout. However, I realize now that I think it could be useful for Markdown pages for sites with a lot of Markdown page content to have this option.

And considering how surprisingly light this implementation is codewise it comes down to the following: Is this a design pattern we want to encourage? And if the answer is no, is that reason enough not to implement this? Even if something is discouraged we can still have the option for users do things the way they want. For some people this might fit their workflow. And since it's opt-in and doesn't add any unnecessary boilerplate for those who are happy with the defaults I think this feature could be useful.

I always like to get user feedback, hence why I drafted this as an RFC, paired with a Twitter poll. In addition to knowing if users are for or against this, I would also love to get feedback on the front matter property name issue mentioned above: if we should use extends or layout.

Voting

Please vote with an emoji on this post:

• Yes: 👍
• No: 👎
• Undecided: 😕

Or vote via the Twitter poll.

Please also leave feedback in the comments!

[caendesilva]

View data ideas

Abstract

Thinking about some additional ways to pass data to the view (as that becomes the responsibility of the developer as we have no knowledge of the helper). These would be a future addition, but am noting them down now as I'm working with this PR in a real project.

Some other static site generators make all front matter properties available in the view. So adding foo: bar in the front matter means that $foo can be used in the view. Hyde does not support this, at least not for now. (The reason I chose not to support this at the time of first thinking of this is because it can cause confusion as we need to filter out some variables form being added as they can cause conflicts)

Currently supported: $page->matter

This works out of the box:

---
image: image.png
---

{{ $page->matter('image') }}

Props idea

What I find meh about the example above in the context of this PR is that you don't get an explicit schema. An improvement could be made so that if the Blade page has @props defined, we can use that to enforce a schema.

For example, the following would require that an image is set in the front matter, but the alt text is optional.

@props([
    'image',
    'alt' => null,
])

With idea

Another idea is to add a with keyword, where any keys would be added to the view. This is basically just adding all the data directly but with extra steps so I'm not sure if this helps anything.

---
extends: layouts/markdown-page-with-header
with:
  image: image.png
  lead: Hello World!
---

There is one benefit of this: It makes it clear that the data is intended for the view. If "image" was added to the root properties, it's not obvious if that is intended for HydePHP to use, or if it's a part of the userland template.

Slots

If we implement #1516, an integration between that and this where slots and stacks could be added to the Markdown could be really nice.

---
extends: layouts/markdown-page-with-header
---

# My page

@push('header')
## My header
@endpush

<x-slot name="footer">
## My footer
</x-slot>

## More stuff

[caendesilva]

Some other static site generators make all front matter properties available in the view. So adding foo: bar in the front matter means that $foo can be used in the view. Hyde does not support this, at least not for now. (The reason I chose not to support this at the time of first thinking of this is because it can cause confusion as we need to filter out some variables form being added as they can cause conflicts)

Noting this is easily resolved, but it could change existing sites so might want it for v2. Anyways, a simple array merge does the trick (it's important that the matter is first in the call)

// Page compile method

$data = array_merge($this->page->matter->toArray(), [
    'title' => $this->page->title,
    'content' => $this->page->markdown->toHtml(static::class),
]);

[caendesilva]

This is now implemented in the experimental Bladedown extension. We can try it out there, and consider merging it here later on. https://github.com/hydephp/bladedown