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.
_config.yml
_posts
published: true
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).
jekyll
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
tailwind.config.js
postcss.config.js
mdsvex.config.js
package.json
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.
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 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 _config.yml file.
Gemfile
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.
src/lib
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.
yarn
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.
src/svekyll/svekyll.js
This file right now defines three functions:
retrieve
sort
processLiquid
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.
svekyll.js
$ 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.