Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jwillikers/blog

My developer blog containing handy admin and dev guides from my myriad of tinkering
https://github.com/jwillikers/blog

asciidoc asciidoctor blog jekyll nix ruby static-site

Last synced: 3 months ago
JSON representation

My developer blog containing handy admin and dev guides from my myriad of tinkering

Awesome Lists containing this project

README 

        
= Blog

Jordan Williams 

:experimental:

:icons: font

ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]

:Nix: https://nixos.org/[Nix]



image:https://github.com/jwillikers/blog/actions/workflows/github-pages.yaml/badge.svg[Deploy, link=https://github.com/jwillikers/blog/actions/workflows/github-pages.yaml]



My developer blog containing handy admin and dev guides from my myriad of tinkering.

Content is written primarily in https://asciidoctor.org/[Asciidoctor].

https://jekyllrb.com/[Jekyll] generates a static website from the content which is then deployed with https://pages.github.com/[GitHub Pages].

The website is available at https://jwillikers.com[jwillikers.com].



== Getting Started



Follow the steps below to build and run the website locally.

Dependencies are managed by {Nix}.



. Install an implementation of {Nix}, such as https://lix.systems[Lix] used here.

+

[,sh]

----

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

----



. Clone the blog's repository.

+

[,sh]

----

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

----



. Change into the blog's directory.

+

[,sh]

----

cd blog

----



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

+

[,sh]

----

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 https://marketplace.visualstudio.com/items?itemName=mkhl.direnv[mkhl.direnv VSCode extension] integrates this environment in VSCode.

The repository contains configuration for https://pre-commit.com/[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.



. Install direnv for your system according to the https://direnv.net/docs/installation.html[direnv installation instructions].

+

[,sh]

----

sudo rpm-ostree install direnv

sudo systemctl reboot

----



. Integrate direnv with your shell by following the instructions on the https://direnv.net/docs/hook.html[direnv Setup page].



. Permit the direnv configuration for the repository.

+

[,sh]

----

direnv allow

----



=== Build



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



[,sh]

----

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.



. 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.

+

[,sh]

----

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.

----



. When finished testing, type kbd:[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.



[,sh]

----

git push

----



The updated website is deployed to https://jwillikers.com[jwillikers.com].



=== Update



Update the Gems with the `just update` command.

This will update the `gemset.nix` file after updating the `Gemfile.lock` file.



[,sh]

----

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 link:CODE_OF_CONDUCT.adoc[Code of Conduct].

If you wish to test the website locally, please see <>.



== Open Source Software



This project is built on the hard work of countless open source contributors.

Several of these projects are enumerated below.



* https://asciidoctor.org/[asciidoctor]

* https://bundler.io/[Bundler]

* https://git-scm.com/[Git]

* https://jekyllrb.com/[Jekyll]

* https://github.com/asciidoctor/jekyll-asciidoc[jekyll-asciidoc]

* https://mmistakes.github.io/minimal-mistakes/[Minimal Mistakes]

* https://rouge.jneen.net[Rouge]

* https://www.ruby-lang.org/en/[Ruby]



== Code of Conduct



The project's Code of Conduct is available in the link:CODE_OF_CONDUCT.adoc[] file.



== License



This repository is licensed under the https://www.gnu.org/licenses/gpl-3.0.html[GPLv3], available in the link:LICENSE.adoc[] file.



The website's content is licensed under a http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons Attribution-ShareAlike 4.0 International License].



© 2020-2024 Jordan Williams



== Authors



mailto:{email}[{author}]