RFC: Theme support for HydePHP Markdown Pages?

[caendesilva]

This proposal is formatted using the proposed new Markdown spec, in the same way a Themed Markdown page would be.

---
title: "Presenting the Hyde SmartTheme Experiment"
theme: demo // Sets the page theme
---

The Hyde SmartTheme Experiment explores the idea of a superset of Markdown
that allows for rich and dynamic control over component-based templates
through code blocks embedded in the Markdown.

By using Yaml code blocks, we can specify the component name and any data
provided to it. This will provide a way to rapidly construct simple pages,
right alongside your Markdown. Since we are exploiting Markdown code
blocks, we even get IDE support and syntax highlighting!

```yaml header
title: "My Header Title"
lead: "Example lead text"
description: "This will render the 'header' component with this Yaml data passed to the view"
```

This would provide a bunch of new interesting opportunities.

Pros:
- Novel approach to Markdown-based pages
- Rapid construction of pages

Cons:
- Dependent on third party themes which may have varying quality
- When initially developing HydePHP, I (the author) intentionally
  made the decision to not support themes due to the complexity,
  bloat, and the risk of overwhelming the user with options.
  For this reason, I chose to instead focus on including
  a versatile and high quality starter template.
  This also distinguishes us from Jekyll.

With these considerations in mind, and any that users are encouraged to submit,
what does the community think about this proposal? Is this something you'd
be interested in seeing? What are your thoughts on the spec?

Please let me know!

[caendesilva]

Alternative syntaxes

# UI Components using Markdown Code Blocks

```hyde-component welcome
yaml: data
pros: shorter syntax, unique, has no conflicts
cons: verbose, requires an IDE plugin
```

```component welcome
yaml: data
pros: unique, has no conflicts
cons: verbose, requires an IDE plugin
```

```yaml hyde-component welcome
yaml: data
pros: has built in IDE support, reduces conflicts, and makes it clearer it's a Hyde component
cons: verbose, the usage of `yaml` as the initial key may be confusing, may have conflicts
```

```yaml welcome
yaml: data
pros: short syntax, has built in IDE support,
cons: the usage of `yaml` as the initial key may be confusing, lack of component keyword may also be confusing. highest risk of conflicts
```

At some point though, this almost becomes a new language and it would lose out on the intended user friendliness. A big bonus with the Yaml syntax compared to a Blade component library however is that this can be managed using a visual frontend, as the Yaml data is fully machine readable/writable.

[sunderee]

As per our conversation, I believe there are some pros and cons to this feature, which you have already described yourself really well.

One of the problems with themes is that there's no real "end" to creating new ones, and trying to satisfy users, especially when requests start flying in about "can I change X in theme Y". So there are two options: make the feature extensible enough that anyone can create their own theme, and perhaps publish it (after review and approval) to some kind of a central store. If we're at this point, might as well expose some kind theme configuration API. Or the second option would be provide some pre-defined themes that are not as extensible (or not extensible at all), but the feature implementation would be much simpler (I imagine...)

But all of that being said, we're entering a real in which you'd be adding a lot of complexity. This complexity may be fine for advanced users, but as you yourself have pointed out, the principal idea behind HydePHP is to be dead simple and "just work" out of the box. Hence why I don't think this should be a central feature, but maybe an extension for advanced users who may need to jump through some extra hoops.

I hope what I wrote here makes sense.

[caendesilva]

That makes total sense, thank you so much for your thoughts! It seems our thinking is very much inline here.

My idea was for HydePHP to provide a few sample themes, and then let the community and third party vendors make the rest. HydePHP would then provide a listing website, where quality themes fulfilling some set of requirements could be marked as verified. These themes would be provided by Composer packages so they could easily be installed.

And as for the complexity and usage case, the way I developed the proof of concept was actually as an extension. I prefer to do that for experimental features.

At this point, while I do think the idea is cool, I'm not sure if it's worth it. Having a well-defined API for Blade component. After all, there is not that much practical difference for advanced users between using this in a Blade file:

@include('theme-name::welcome', ['yaml' => 'data', 'foo' => 'bar'])

As always, I'm super grateful for your help and really appreciate your thoughts on the matter!

[caendesilva]

Closing this discussion as resolved, since while this specific implementation is cool, it might not actually solve any problems. Theme support in general can stand on its own as a separate issue.

[caendesilva]

Just putting it here that GitHub uses [brackets] for their magic code block features like tasklists. Could be on the way to setting a standad?

```[tasklist]
- Item
```

[caendesilva]

New promising package

@blade
    <!-- Put my custom Blade code here. -->
@endblade

https://ryangjchandler.co.uk/posts/embedding-blade-inside-of-markdown-content

https://github.com/ryangjchandler/commonmark-blade-block