Distill template

[mathisonian]

It seems like there is a bit of excitement around the article template that Distill offers, e.g. it has been picked up by r markdown: https://rstudio.github.io/distill/.

Would people be interested in including this as a built-in theme for Idyll articles?

[jbixon13]

@mathisonian I've replicated a lot of distill's templating and have started locally developing an idyll theme for it; what is the best way to understand how themes, templates, & layouts interact within idyll?

It seems like I cannot truly start from a blank slate even when building my distill theme off of the existing blank template in idyll. There is additional CSS that is input to idyll_styles.css (possibly from the chosen template & layout?). Additionally, distill uses CSS grid for its article title/description. How do I create a theme that replicates this if the HTML structure needs to change to accommodate this (I haven't fully investigated this, but I suspect it would be necessary to translate the article from distill to idyll)

For example: A distill article has the following article title/header:

This is structurally different from an idyll article; how would I write a theme that allows for this without changing any of the HTML that is provided through (I assume) the article template or blog layout?

Another question to help understand this: how can I better understand how CSS classes are used within idyll articles? Looking at the default theme's styles.js it is difficult to tell what is used where and how to convert from distill's theming to idyll's.

[jbixon13]

@mathisonian any feedback on these points?

[mathisonian]

Hey @jbixon13 thanks for the poke and your patience on this.

what is the best way to understand how themes, templates, & layouts interact within idyll

In Idyll themes and layouts are CSS-only concepts that don't touch the actual HTML of the page. When you run idyll, a CSS file will be generated that is the concatenation of the layout CSS, the theme CSS, and any user-provided CSS. The rule of thumb is that style rules which deal with aesthetics like fonts, colors, etc go into a theme, and other rules which deal with structural issues like e.g. 'placement of the text column' go into layout. If you want to get a truly blank slate in CSS you can set your theme and layout both to none.

In contrast to themes and layouts, a project template represents a "preconfigured" idyll project, with settings chosen to make it easier to achieve a certain task. A template is essentially a snapshot of an idyll project configuration; once you've created a project based on a template there is no magic behind the scenes CSS or HTML associated with that template.

This [header] is structurally different from an idyll article; how would I write a theme that allows for this without changing any of the HTML that is provided through (I assume) the article template or blog layout?

So far we haven't supported themes that modify HTML as all of the changes they've made is through CSS rather than HTML. However there are a few options to achieve this. First, it should be noted that the [Header /] component structure is defined here. We do our best to try to write components that are decoupled from the themes themselves. In this case the header component defines certain classNames which are styled via the themes.

So one option is to modify the header component so that it is extensible enough to support the distill-style layout above; this might mean thinking about using CSS grid to support specifying content placement directly in a theme's CSS.

An alternative approach is to ship a distill theme that does everything possible excluding structural HTML changes, and then separately make those available for people as well, e.g. by creating a new [DistillHeader /] component. This component could be distributed via npm or we could set up a project template for distill posts that includes it by default.

Another question to help understand this: how can I better understand how CSS classes are used within idyll articles? Looking at the default theme's styles.js it is difficult to tell what is used where and how to convert from distill's theming to idyll's.

I think I'd need understand how CSS classes are used by distill a little better to say much useful here, but I can say: in idyll CSS classnames are defined by the components. For the most part we try to follow the convention of class names like .idyll-<component-name> (although unfortunately we're not 💯% consistent with this yet).

User's can also add additional content-specific class names to components in their articles, but I don't think we need to worry about that here.

---

I'm open to any and all suggestions about alternative ways of handling this. Its really the first time we've run into the issue of wanting to customize both CSS and HTML for a particular theme.

[jbixon13]

Thank you for the detailed answers! I won't be able to give this too much time at the moment but I will think over your feedback for when I can make some progress on it.

I do think your second approach (superficial changes in a theme, then creating a new component to accommodate structural changes) makes the most sense to me.

One other thing that may complicate things is how media queries are handled in idyll. In distill CSS is defined as mobile-first and then overwritten for larger screens where necessary. I have not yet been able to see how it is handled in idyll but I will investigate this as well.

[mathisonian]

Sounds good @jbixon13!

In Idyll's CSS we start with the desktop and transform to a smaller grid in the CSS queries. So, there may be a little bit of friction there, but I would imagine not too much if you're overriding many of the existing CSS rules anyway.