Using Stock Jekyll Themes @ stwoo.net

This covers a different case than Migrating from Jekyll: not porting your own existing site, but grabbing someone else’s Jekyll theme repo and running it as-is.

The workflow

git clone https://github.com/<owner>/<theme-repo>.git
cd <theme-repo>
gohyde doctor          # environment sanity check: Dart Sass, _plugins/, _config.yml
gohyde migrate --fix   # compatibility report + best-effort Ruby filter auto-port
gohyde serve           # build + watch, http://localhost:4000

gohyde doctor and plain gohyde migrate are read-only. --fix only ever writes two things: sdk/python/gohyde.py / sdk/ruby/lib/gohyde.rb (reference SDKs for porting plugins by hand) and, for any _plugins/*.rb file that reopens Jekyll::Filters or calls Liquid::Template.register_filter, a <name>.gohyde.rb written next to the original — the one Jekyll plugin idiom mechanical enough to translate automatically (see Migrating from Jekyll). It does not touch _config.yml or any template/content file — undefined-filter and undefined-tag errors in the theme’s own Liquid still need a manual fix, same as real Jekyll would need if the theme were genuinely broken.

remote_theme: doesn’t work

A _config.yml using GitHub Pages’ remote_theme: owner/repo key won’t resolve — Gohyde never fetches a theme over the network, at build time or otherwise. gohyde migrate flags this key as unsupported. Clone the theme repository directly (as above) and build from inside it, or copy its _layouts / _includes / assets / _sass into your own site.

Errors you’ll actually hit

Stock themes carry real bugs of their own. Most undefined filter "X" / undefined tag "X" errors below turn out to be the theme’s mistake, not Gohyde’s — before assuming a compatibility gap, check whether real Jekyll would fail identically: does X actually exist in Jekyll’s documented filter list or the Liquid gem’s own? Does the theme’s Gemfile declare a plugin that provides it?

• undefined filter "relURL" / "absURL" — not real Jekyll filters, a different static site generator’s (Hugo) naming convention. The theme meant relative_url / absolute_url.
• undefined filter "url_escape" / "camelcase" — found live on a still-maintained, widely-used theme. Neither exists in the Liquid gem or Jekyll’s own filter set, at any version — real Jekyll fails the same way. Swap in uri_escape, or drop the filter if it’s purely cosmetic.
• undefined filter "add" — Jekyll’s arithmetic addition filter is plus, not add.
• undefined tag "gist" — real jekyll-gist syntax ({% gist id [file] %}), which Gohyde implements natively: the <script> embed tag, without the gem’s noscript fallback (that needs a live network call at build time). See Liquid & Jekyll compatibility.
• layout "X" not found", where X lives under a _layouts/ subdirectory (layout: vendor/compress) — fixed; layout loading is recursive.
• include "/foo.html" not found — a leading slash in {% include %} is absorbed the same way Jekyll’s File.join absorbs it, not treated as an absolute-path override.
• cannot unmarshal !!map into string on _config.yml, from a nested author: {name: ..., bio: ...} block instead of a plain string — both forms are accepted; if you hit this, you’re on an old Gohyde build.
• A Sass entry point built almost entirely out of {% if %} / {% include %} fails to compile (a theme’s color-scheme .scss, typically) — Liquid now runs over front-mattered Sass entry points before handing them to the compiler, matching real Jekyll’s Sass converter.
• Post filenames with unpadded month/day (2016-8-20-post.md) — accepted, matching Jekyll’s own lenient date-filename matcher.

If you hit something not on this list and you’ve confirmed real Jekyll would render it fine, that’s a genuine Gohyde gap — report it to beta [at] stwoo.net.

Plugins

_plugins/*.rb / *.py files don’t run through Jekyll’s Ruby process at all — they need porting to Gohyde’s own plugin SDK. gohyde doctor’s “Jekyll plugins” check and gohyde migrate’s fuller report both tell you, per file, whether it’s auto-portable, needs a manual rewrite, or is blocked entirely (direct Jekyll::Site / Jekyll::Page access, hard-blocked since there’s no equivalent object model to translate to). See Writing Plugins and the plugins section of Migrating from Jekyll.

Verifying it actually matches

Worth doing once per theme (you’re really testing its layouts/includes, not your own content) — same recipe as Migrating from Jekyll:

jekyll build -d _jekyll_out
gohyde build -d _gohyde_out
diff -r _jekyll_out _gohyde_out

Whitespace and attribute ordering may differ; semantic differences are bugs.