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.

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.

Getting Started

The steps below will create an environment for generating the website locally. These steps assume you are on Fedora and familiar with the Linux command-line and Git.

1. Clone the blog’s repository.

   git -C ~/Projects clone git@github.com:jwillikers/blog.git

2. Change into the blog’s directory.

   cd ~/Projects/blog

3. Install the dependencies needed for asdf.

   sudo dnf -y install gcc gcc-c++ libffi-devel ruby-devel rubygem-bundler

4. Configure a project-specific directory for Gems.

   bundle config set --local path 'vendor/bundle'

5. Install the required Ruby gems.

   bundle install

Build

The website can be generated locally by passing the b subcommand, i.e. build, to Jekyll.

bundle exec jekyll b

Test

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 running Ubuntu with the GNOME desktop.

1. Run the jekyll executable with the s subcommand, i.e. serve.

   bundle exec jekyll s
   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. Open the server address provided in the previous output with your web browser of choice.

   open http://127.0.0.1:4000/

3. 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 bundle update command.

bundle update

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-2023 Jordan Williams

Authors

Jordan Williams