Jekyll is a statis site generator written in Ruby by the great Tom Preson-Wener (founder and former CEO of Github, aswell as prolific blogger/educator). It takes text content (in the form of Markdown, .md, files) and templates (HTML layouts) and converts them into a complete static website that can be served without a backend or database.

Once you have set up the boilerplate (still a slighty non-trivial matter for a noob like me, not not too difficult, especially for a bare-bones setup) all you have to do is add .md files to _posts/ and any linked images/video/audio etc. to assets/ and run the command bundle exec jekyll serve, and the static site html is automatically generated and hosted locally on your machine. You can then easily push this repo to Github and have it hosted on Github Pages for free!

Some useful commands:

  • bundle install -> Installs the gems (libraries of code, similar to python libraries but managed using Gemfile via Bundler, the Ruby dependency management tool) specified in the Gemfile.
  • bundle update -> Updates the gems in the Gemfile to the latest acceptable version.
  • bundle exec -> Executes a command in the context of the bundle, i.e using all the gems and versions specified in Gemfile.lock.

  • jekyll new <site-name> -> Creates a new Jekyll site in the directory with the required structure and example files.
  • jekyll build -> Compiles the site and outputs static files to the _site directory.
  • jekyll serve -> Builds the site and serves it locally via development server, typically available at http://localhost:400. It automatically rebuilds and regenerates the site when files are edited.
  • jekyll clean-> Removes generated files such as the _site directory.

  • bundle exec jekyll serve -> Builds and serves the static sit locally using the exact dependencies defined in Gemfile.

  • bundle exec jekyll serve --source <source_dir> -> Builds and serves the site, with the source directory sotred in instead of the default `./` (current directory).
  • bundle exec jekyll serve --verbose -> Increase the verbosity of information about the build and serve process, usefull for debugging.
  • bundle exec jekyll serve --port 5000 -> Serve the jekyll site locally to the specified port (in this case 5000) instead of the default port 4000.
  • bundle exec jekyll serve --drafts -> Include posts in the _drafts/ directory in the build/serve.
  • bundle exec jekyll serve --future -> Include posts in the _posts/ directory that have their frontmatter date set in the furute. E.g. a file with the name 2025-01-15-post.md, if the current date is before the 15th.

Port termination

I had the problem where a jekyll site was running on the default port (4000), but I couldn’t find it to terminate it. To do this I used lsof -i :4000 (python lsof is the list open files command) which lists all the processes bound to port 4000. This prints the info for running processes on that port along with the process ID (PID), which can be killed using kill <PID>. kill -9 <PID> is forceful kill of the PID, if kill <PID> doesn’t work. You can also use pkill -f <COMMAND> to kill a command with a specific name, for example pkill -f ruby in the case of killing a Jekyll served website.