deirdre.dev

There's a saying in web dev: when you hit a wall, start or redesign a site.

While I like Jekyll, I've found that, because I no longer spend my days in TextMate, I don't think about my website frequently. It's a habit thing.

So I've been looking into Publish (given that I live in Xcode), and there's really very little information about how to build your own site theme if it needs anything more than the most basic of website function.

Also, while Markdown is fantastic for laying out prose within a document, it doesn't represent the semantic parts of a page newly available in HTML5 (e.g., article, figure, figcaption, header, footer, nav, section) that help accessibility as well as search engines. Granted, Publish does have at least most of those, but you'd have to create code to inject them into your page.

Themes

Publish developer John Sundell suggested that everyone write their own theme for their site. While, yes, that is ideal (with limitations), having at least one medium complex good example can really help speed up a first implementation.

Here are the ones that were most useful, with commentary.

• Casperish port of Ghost's Casper theme by sowenjub and aure. This isn't strictly a Publish theme, though, because of the extras it brings in, but some of how it solves some issues are worth looking at. One notable downside is the utter lack of tests. Deployed site here. One of the technically interesthing things is that there's a protocol for the theme, rather than the usual way of just having the struct conform to Website, it also has to conform to CasperishWebsite.
• Radio Seara by Goosse. New theme with deployed site here. Reasonably simple, but clean looking. Love the aesthetic of it! (No tests, though.)
• CoolOneOfficial's personal site theme has nice layered metadata handling. Deployed here (in Russian). Site also uses several plugins, which may be useful. And no tests.
• pvzig's theme swaps out Sundell's Markdown parser for Common Mark. Site is deployed here. I really like the grey/green combo. No tests.
• Yusuf Özgül's theme for his site, which is mostly in Turkish. Despite the relatively simple theme, he's got a fairly intricate set of conditionals, which may help you sort out how to write your own theme. No tests. Also interesting is a loader class that creates the static pages of the site.
• Bill Donner has written several band sites with variants on his theme. And, guess what? There are tests! o/ Seriously, folks, John Sundell's got an excellent test suite for Publish and its dependencies, and y'all should take the time to level up on tests.
• Demacia's theme is interesting in that it uses a lot of plugins and…wait for it…many are npm. Site deployed here for an Israeli robot club. No tests (again).
• Leonte.dev's theme has some custom publishing steps, including rewriting. Deployed here. No tests.
• Christian Elies's theme isn't particularly complex, but the way the meta data and tags are broken out is very orderly. Also has some nice examples of how to do card elements on a page. No tests.
• Weissazool has a minimalist photo blog theme. Deployed here. Not super duper different than the default, but a nice example of image and post together and how to do that. No tests.
• Joe Blau's got a really old skool retro theme that is very winning at the end. It's the kind of site you can make when you know your experience and chops are so good that you can just…retro it. Deployed here. No tests.
• Fatbobman's theme isn't super revolutionary, but there are some interesting plugins written for it. Deployed here (note: site's in Chinese, and so are the code comments). No tests.
• Several people have used a variant of this theme; the earliest version I found was from Lithuanian dev Povilas Staškus. It's a really nice clean-looking theme, deployed here. No tests.
• Oliva isn't a theme in the traditional sense. It instead generates fantasy baseball team game data. It does use Publish, though, and it uses it in an interesting way. No tests.

Others:

• SanTheme, though I couldn't find a deployed site. No tests.
• SwiftVietnam's theme, deployed at SwiftVietnam.com. Basic Foundation-style theme, but may be of interest to Vietnamese readers. No tests.
• Just a Bunch of Grapes has some interesting metadata, but I didn't see it deployed anywhere. No tests.

So…1 out of 17 had tests.

Why No, I haven't Said Enough On That Topic

Seriously, John Sundell's done an excellent job of making tests easy to understand and write.

Here's one of the stylesheet tests:

     func testCSSStylesheet() {
        let html = HTML(.head(.stylesheet("styles.css")))
        assertEqualHTMLContent(html, """
        <head><link rel="stylesheet" href="styles.css" type="text/css"/></head>
        """)
    }

It will help you when you (almost inevitably) want to refactor later.

Did I Leave You Out?

I have looked at a ton of Publish sites over the last couple of weeks, enough so that my eyes melted more than once. ;)

Generally, I was looking for something specific, so if I didn't see it, I may not have kept that tab open long enough to get around to writing this post. Also, I only looked on Github, so those hosting their themes on Gitlab or other platforms were left out.

Please feel free to ping me if you've got a site that you think shows some interesting use of Publish, especially if it has tests. I'm mostly interested in one of two kinds of sites:

1. Sites that have more complex markup, e.g., a port of a commercial-quality theme like those found at HTML5Up.net. (I'm currently working on Solid State, thus wanted to find more examples on that order of complexity.)
2. Sites that are using plugins or unusual publishing pipelines. However, apart from the single example above, sites that use JS steps need not apply.

• swift
• publish