Guidance on porting a theme

[Kadeykin12]

Hey,

I am trying to port the Hyde theme (https://github.com/poole/hyde) from Jekyll over to Wyam to use with a blog but I am having a hard time figuring out where to start. Are there any instructions or examples that I could look at?

[daveaglick]

I've ported a couple Jekyll themes, so it's certainly possible. I keep meaning to write a guide with step-by-step instructions, but I've got nothing yet. I can give you some pointers though:

• Change the extension on the files under _layouts to .cshtml - these will now be Razor templates (Wyam will eventually support Liquid, but for now Razor is the only Wyam template language that supports layouts). Do the same for files in _includes.
• By convention, Razor templates typically go under a folder named Shared, so rename _layouts to Shared and also move the files from _includes to the Shared folder.
• Replace the Liquid commands denoted by {% ... %} with Razor ones. Razor should have an equivalent for every Liquid command, let me know if you need some help figuring out the equivalents.
  • In cases where the Liquid template is pulling documents and content provided by Jekyll (I.e., {% for post in site.related_posts limit:3 %}) you'll need to replace that will the equivalent Wyam document/metadata. The set of documents can be retrieved within a Razor page with the Documents property.
• Move the files in public to the root of your site.

In the near future, Wyam will include it's own theming capability which should make this sort of thing easier (mostly because I'll go through a process of finding common MIT-licensed themes like Hyde and converting them once for everyone to use).

[Kadeykin12]

Hey Dave,

Thanks for this info. I will have some free time next week, so I will play around with it and see how far I can get. I will put a repo on GitHub so that you and other can see and chime in as necessary.

As for the theming capability, do you have an inclination of when that might be available? Weeks? Months? I am debating using Jekyll or Hugo for a couple projects that I have, mainly because of the availability of already built themes. It would be nice if Wyam had this in the near future.

[daveaglick]

It's "next up" but timing is tough to estimate with OSS since you don't know day-to-day how much time will be available. What I can tell you is these are the things that need to happen for themes:

• Finish up the Windows installer (probably today)
• Change some of the docs for the next release (probably a day or two)
• Prep and publish the next release
• File provider URI changes (#277)
• Support directives on the CLI (#280)
• Recipes (#1) - important because a theme only applies to a particular set of build instructions

If I had to take a wild guess, I'd say themes are still a couple months out (but closer to 2 months and not 6). Just about everything is in service to the goal of single-command execution right now because I think that's the thing that's going to get the project into many more hands. I.e., when you can just write a command like wyam -recipe Blog -theme CoolTheme and have it just work, I think a bunch of people will give it a look.

[Kadeykin12]

I.e., when you can just write a command like wyam -recipe Blog -theme CoolTheme and have it just work, I think a bunch of people will give it a look.

Yes, most definitely agree with that.

What do you see in terms of the upgrade path once recipes and themes land in master? It's probably hard to tell without having a clear idea of the implementation but I am curious if I would be able to easily take any efforts to port the themes now and move them to the new system without essentially re-doing them.

[daveaglick]

Honestly not sure. The difficulty will probably depend on how close the recipe is to the theme you're porting.

Unlike Jekyll or other more focused generators, Wyam is really flexible so a given configuration (what I keep referring to as a "recipe" is just a canned configuration) could do any number of things. That's why the themes are going to be tied to the recipe they support. It wouldn't make sense to have a theme for blogs get used for a site with API documentation. Critically, all the metadata will probably be different between the two recipes so if one theme knows to look for a PublishedDate metadata value from the blog recipe, that wouldn't even be there for other recipes.

All that said, I can tell you the initial blog recipe and themes are probably going to be pretty similar to my own blog (https://github.com/daveaglick/daveaglick). Your theme obviously wouldn't need to use the same markup, stylesheets, images, etc. but if it uses the same metadata and document conventions, it'll probably be easier to port later.

[daveaglick]

I'm going to go ahead and close this issue - feel free to request we reopen it or to file a new one if you have any follow-up questions.