Migrating from Jekyll @ stwoo.net

Gohyde reads the same _config.yml, front matter, layouts, includes, and
collections as Jekyll, so most sites build with little or no change. This guide
covers the friction points that show up on real sites.

Steps

1. Point Gohyde at the site and build:

   cd my-jekyll-site
   gohyde build
   

2. Read the warnings. Missing assets, Sass fallbacks, and unknown tags all
   warn to stderr without failing the build. Work through them.
3. Clean the output dir if you see stray files: rm -rf _site _builds.

What works unchanged

• Liquid templates, including most Jekyll-lenient syntax (see
  Liquid compatibility — the compat preprocessor handles
  filter == true-style conditions).
• Front matter, defaults, permalinks (date/pretty/ordinal/none/custom).
• Collections (incl. _posts), pagination, data files.
• {% include %} with parameters and runtime values.
• Kramdown sites — Goldmark renders them; emoji and syntax highlighting included.

Common adjustments

url and baseurl

Asset URLs and page URLs include baseurl. Make sure absolute links prepend
{{ site.url }} explicitly:

<link rel="canonical" href="{{ site.url }}{{ site.baseurl }}{{ page.url }}" />

If site.url is blank, links render relative — uncomment url: in _config.yml
for absolute URLs.

Sass

Install Dart Sass (npm i -g sass or your package manager). The legacy Ruby
sass gem is detected and skipped. Without a real compiler, SCSS passes through
unprocessed with a warning.

jekyll-assets-style tags

{% asset %}, {% javascript %}, {% stylesheet %}, {% image %} and the
@path/@url/@uri URL-only flags are supported. See Assets.

Plugins

Ruby/Python Jekyll plugins don't run as-is — port them to Gohyde's plugin SDK
(see Writing Plugins). Two Ruby idioms that differ:

• Liquid::Template.register_tag → the tag DSL. A Jekyll tag class
  becomes a tag :name do |args| … end block.

• return inside a block raises LocalJumpError. Jekyll tag code that does
  an early return inside an iterator must be rewritten. Use find / .lazy
  instead of .each + return:

  # Jekyll plugin (won't work as a Gohyde tag block):
  pages.each { |p| return p.url if p.slug == target }
  
  # Gohyde tag block:
  tag :entrylink do |args|
    target = args.strip
    page = @pages.find { |p| p["slug"] == target }
    page ? page["url"] : ""
  end
  

  For nested searches, .lazy.flat_map { … }.first avoids the early-return
  problem entirely.

jekyll-feed, jekyll-seo-tag, etc.

Gem-based tag plugins ({% feed_meta %}, {% seo %}) aren't bundled. Inline the
markup or port the plugin:

<link type="application/atom+xml" rel="alternate"
      href="{{ site.url }}{{ site.baseurl }}/feed.xml"
      title="{{ site.title }}" />

Verifying parity

Run the same site through both generators and diff the output:

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 —
Jekyll's output is the spec.