How does Svekyll differ from Jekyll?

The starting point for building Svekyll was to build something that respects the simplicity of Jekyll. That means supporting and centralizing things around a simple configuration file called _config.yml. And, making it easy to drop markdown files into (a symlink) directory called _posts. All files with an .md extension automatically get turned into a static file with the same name (minus the .md extension). And, you also need to add a published: true inside the YAML front matter in those files to indicate you want to publish the file.

But, there are differences between Svekyll and Jekyll. This post will summarize them, and point out why those decisions were made.

First, Svekyll is not a command which processes a directory, it is an entire app built on the SvelteKit app framework.

With Jekyll, you install a ruby gem called jekyll, and then you run that command on a directory of files which jekyll processes and generates a set of static files which you can put onto a web server (or push into a git repository and have a that code service do all that for you).

With Svekyll, you have a repository of an entire set of files for an app (the app is a SvelteKit app).

One consequence of having an entire app framework is that you then have a bunch of configuration files in your directory (that will also be managed in your source code repository when you publish your blog).

You as a user of Svekyll should almost never need to look at these files to use Svekyll. But, if you want to customize your blog, you have the full power to do so.

Those files are:

  • svelte.config.js: The svelte configuration file (see: Svelte).
  • tailwind.config.js: the Tailwind CSS configuration file (TailwindCSS).
  • postcss.config.js: The PostCSS configuration file (PostCSS).
  • mdsvex.config.js: The MDSvex configuration file (MDSvex)
  • package.json: The NodeJS package file, which contains build commands and packages used by your app.

You should not need to modify (or even read!) these configuration files at all , and out of the box they provide some powerful features for you. But, you can change them if you want to enable a new feature, or Svekyll has not yet integrated something that these tools offer. You have full control.

Second, upgrading can be a little trickier, but also can be as easy as running git pull.

Upgrading jekyll means installing the latest version of the ruby gem tool. In most cases, this will work, but you can imagine there are times when an upgrade breaks because the files it is compiling have unsupported features.

With Svekyll, for now, you pull the latest changes into your fork of the repository. This means you need to review those changes (use a feature branch), and you can see all the changes in your git history.

To upgrade you can add a git remote, then checkout to a branch, then fetch the upstream and merge it into your branch. Then, run yarn dev, check out whether it works, and then merge onto main. For example, those commands would look like this:

git remote add upstream
git checkout -b merge_latest # create a branch to test on
git fetch upstream main      # get the latest changes
git merge upstream/main      # merge the upstream changes into your branch
yarn dev                     # Look at it in the browser, does it look OK?
git checkout main            # go to main 
git merge merge_latest       # merge from your test branch
git push origin main         # publish your changes

Svekyll is currently in alpha, so there are often breaking changes. And, we are working hard to put testing in place to reduce these breaking changes and let you know when they happen.

(If you host on ExtraStatic, and you have pulled in files that broke your build, the new push won’t publish new files.)

Third, Svekyll does not support plugins in the same way that Jekyll does

With Jekyll, you provide a list of plugins inside your Gemfile file, and then enable them in your _config.yml file.

With Svekyll, you would typically add whatever code you need by pulling in node modules (adding them to package.json) and then adding code in the src/lib directory, or whatever was appropriate.

Over time, there will probably be Svekyll plugins. Those might be something you can enable in the _config.yml file, or they might be something you can install using yarn or npm.

You can customize the processing of files in whatever way is best right in the repository

Svekyll processes files using the tools that come with SvelteKit: vite and mdsvex and other nodejs tools. The processing starts in the src/svekyll/svekyll.js file so if you want to learn about how things work, you can look into there.

This file right now defines three functions:

  • retrieve: pull in the set of markdown files.
  • sort: sort the slurped in markdown files (and permit overriding inside the _config.yml file).
  • processLiquid: a starting point for processing liquid files in Svekyll (so we can support basic liquid tags found in common jekyll blogs)

svekyll.js also has a good starting point for test coverage. If you want to experiment with changing it, make sure you run the tests to see that things work correctly when you are done.

$ yarn test
yarn run v1.22.10
warning package.json: No license field
$ mocha ./tests/*.spec.js

      ✔ should get correct date from files with date in the filename
Unable to process date, please add date to YFM for your posts or name your post 2021-12-12_filename TypeError: Cannot read property 'split' of undefined
      ✔ should have readingTime at 0 if a small file
Unable to process date, please add date to YFM for your posts or name your post 2021-12-12_filename TypeError: Cannot read property 'split' of undefined
      ✔ should have good readingTime
      ✔ should get date from YFM, preferring over filename
      ✔ should get date filename if missing in YFM
      ✔ should not crash
      ✔ should reverse
      ✔ should sort by a key
      ✔ should support list of sort options
      ✔ should support list of sort options with spaces
      ✔ should remove empty items with nonulls

  11 passing (12ms)

Done in 0.25s.