Freeze First Code Blocks

GitHub Action to parse and convert first found code block in files to image via Freeze

---

• ⬆ Top of Document
• 🏗 Requirements
• ⚡ Quick Start
• 🧰 Usage
• 🗒 Notes
• 📈 Contributing
  • 🔱 Forking
  • 💱 Sponsor
• 📇 Attribution
• ⚖ Licensing

---

Requirements

Awk, GAwk, or MAwk must be installed in addition to bash, find, and jq, to make use of scripts within this repository;

• Alpine

  sudo apk add --no-cache bash findutils gawk jq

• Arch BTW™

  sudo pacman -S bash findutils gawk jq

• Debian derived distributions

  sudo apt-get install bash findutils gawk jq

... And for the latest/greatest version of freeze it is recommended to install Golang, which varies from distribution to distribution;

go install github.com/charmbracelet/[email protected]

... Finally, for now, access to GitHub Actions if using on GitHub, or manually assigning environment variables prior to running ./entrypoint.sh should be all that be necessary to satisfy requirements for this repository.

---

Quick Start

Usage

Reference the code of this repository within your own workflow file under jobs.steps section;

      - name: Find and freeze first code blocks in posts
        uses: gha-utilities/[email protected]
        with:
          source_directory: _posts
          find_regex: '.*.md'

... For completeness the following be a fully functional example for customized Jekyll built site deployed to GitHub Pages;

on:
  push:
    branches: [ gh-pages ]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Cache assets/images
        uses: actions/cache@v4
        id: cache-images
        with:
          key: cache-images
          path: assets/images

      - name: Checkout source
        uses: actions/checkout@v4
        with:
          fetch-depth: 1
          fetch-tags: true
          ref: ${{ github.head_ref }}
          submodules: 'recursive'

      - name: Find and freeze first code blocks in all collections
        uses: gha-utilities/[email protected]
        with:
          source_directory: './collections'
          find_regex: '.*.md'
          find_regextype: 'emacs'
          sed_args: '-E'
          sed_expression: 's@collections/_@assets/images/@'
          freeze_config: './ci-cd/.config/freeze/user.json'

      - name: Convert with ImageMagick -- first-code-block
        uses: gha-utilities/[email protected]
        with:
          source_directory: assets/images
          find_regex: '.*first-code-block.png'
          destination_extensions: avif,jpg

      - name: Convert PNG images to WebP -- first-code-block
        uses: gha-utilities/[email protected]
        with:
          source_directory: assets/images
          find_regex: '.*first-code-block.png'
          cwebp_opts: '- q 60'

      # ↓ Do some site building here ↓
      - name: Setup pages
        uses: actions/[email protected]
      - name: Build pages
        uses: actions/jekyll-build-pages@v1
      # ↑ Do some site building here ↑

      - name: Upload artifact
        uses: actions/[email protected]

  deploy:
    runs-on: ubuntu-latest
    needs: build

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/[email protected]

---

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

Check the ./action.yaml file for all input/output-s available as well as up-to-date examples where applicable.

---

Contributing

Options for contributing to freeze-first-code-blocks and gha-utilities

---

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is [email protected]:<NAME>/<REPO>.git...

cd ~/git/hub/gha-utilities/freeze-first-code-blocks

git remote add fork [email protected]:<NAME>/freeze-first-code-blocks.git

• Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/gha-utilities/freeze-first-code-blocks


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

---

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as freeze-first-code-blocks that gha-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

---

Attribution

• CSS Tricks -- The Essential Meta Tags for Social Media
• GitHub -- bash-utilities/failure
• GitHub -- community/discussions -- 106666 -- For multi-line outputs
• GitHub -- github-utilities/make-readme
• GitHub -- jekyll/jekyll-seo-tag

---

License

GitHub Action to parse and convert first found code block in files to image via Freeze
Copyright (C) 2025 gha-utilities

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.