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
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 https://extrastatic.dev/jekyll/jekyll 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
With Svekyll, you would typically add
whatever code you need by pulling in node modules (adding them to
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
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
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 #svekyll #retrieve ✔ 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 #sort ✔ 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.