Blog

My developer blog containing handy admin and dev guides from my myriad of tinkering. Content is written primarily in Asciidoctor. Jekyll generates a static website from the content which is then deployed with GitHub Pages. The website is available at jwillikers.com.

Getting Started

Follow the steps below to build and run the website locally. Dependencies are managed by Nix.

1. Install an implementation of Nix, such as Lix used here.

   curl -sSf -L https://install.lix.systems/lix | sh -s -- install

2. Clone the blog’s repository.

   git clone [email protected]:jwillikers/blog.git

3. Change into the blog’s directory.

   cd blog

4. Build and run the blog locally with Nix by running the default app.

   nix run

Development

This project’s Nix flake provides a development environment which can be entered by running the nix develop command. For convenience, direnv can be used to automatically load this environment when entering the project’s directory. The mkhl.direnv VSCode extension integrates this environment in VSCode. The repository contains configuration for pre-commit, which can be used to automate formatting and various checks when committing changes. Follow the instructions here to set up your development environment.

1. Install direnv for your system according to the direnv installation instructions.

   sudo rpm-ostree install direnv
   sudo systemctl reboot

2. Integrate direnv with your shell by following the instructions on the direnv Setup page.

3. Permit the direnv configuration for the repository.

   direnv allow

Build

The website can be generated locally with the jekyll build command.

jekyll build

Jekyll supports running a web server on the local machine, which can be used to preview and test changes to the website. The steps below describe how to do this below, assuming you are in the project directory.

1. Run the jekyll executable with the serve subcommand. The --open-url flag is handy for automatically opening the server at http://127.0.0.1:4000/ in your browser.

   jekyll serve --open-url
   Configuration file: /home/jordan/Source/blog/_config.yml
               Source: /home/jordan/Source/blog
          Destination: /home/jordan/Source/blog/_site
    Incremental build: disabled. Enable with --incremental
         Generating...
          Jekyll Feed: Generating feed for posts
    Auto-regeneration: enabled for '/home/jordan/Source/blog'
       Server address: http://127.0.0.1:4000/
     Server running... press ctrl-c to stop.

2. When finished testing, type Ctrl+C to stop the local web server.

Deploy

Continuous integration is configured through GitHub Actions. Trigger the CI to build and deploy by pushing changes to the main branch on the GitHub remote.

git push

The updated website is deployed to jwillikers.com.

Update

Update the Gems with the just update command. This will update the gemset.nix file after updating the Gemfile.lock file.

just update

Contributing

Contributions in the form of issues, feedback, and even pull requests are welcome. I really appreciate pointing out typos, incorrect instructions, and ways to improve or simplify posts. Considering this my personal blog, you will want to create an issue or contact me before making any significant pull request. Make sure to adhere to the project’s Code of Conduct. If you wish to test the website locally, please see Getting Started.

Open Source Software

This project is built on the hard work of countless open source contributors. Several of these projects are enumerated below.

• asciidoctor

• Bundler

• Git

• Jekyll

• jekyll-asciidoc

• Minimal Mistakes

• Rouge

• Ruby

Code of Conduct

The project’s Code of Conduct is available in the CODE_OF_CONDUCT.adoc file.

License

This repository is licensed under the GPLv3, available in the LICENSE.adoc file.

The website’s content is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

© 2020-2024 Jordan Williams

Authors

Jordan Williams