feat(shortcode): initial release

tgagor · Mar 8, 2024 · 214121d · 214121d
1 parent 86cff7d
commit 214121d
Show file tree

Hide file tree

Showing 15 changed files with 628 additions and 0 deletions.
diff --git a/.github/workflows/test-and-release.yml b/.github/workflows/test-and-release.yml
@@ -0,0 +1,57 @@
+name: Generate test site to ensure it works
+
+on:
+  push:
+    branches:
+      - main
+      - feature/*
+      - bugfix/*
+
+jobs:
+  build-exampleSite:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 1
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: 0.121.2
+          extended: true
+
+      - name: Test if exmapleSite can be built
+        run: |
+          cd exampleSite
+
+          # install PaperMod theme
+          git clone --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
+
+          # install hugo-kofi-shortcodes
+          ln -s ../ themes/hugo-kofi-shortcodes
+
+          ls -la themes/
+
+          hugo --minify
+
+          # clean up
+          rm -rf themes/*
+
+      - name: Bump version and push tag
+        if: github.ref == 'refs/heads/main'
+        id: tag_version
+        uses: mathieudutour/github-tag-action@v6.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create normal GitHub release
+        if: github.ref == 'refs/heads/main' && github.event_name != 'schedule'
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.tag_version.outputs.new_tag }}
+          release_name: Release ${{ steps.tag_version.outputs.new_tag }}
+          body: ${{ steps.tag_version.outputs.changelog }}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+exampleSite/themes
+*.lock
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,38 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=auto]
+      - id: check-added-large-files
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: pretty-format-json
+        args: [--autofix, --indent=4, --no-sort-keys]
+
+  - repo: https://github.com/boidolr/pre-commit-text
+    rev: v1.2.13
+    hooks:
+      - id: pretty-format-yaml
+        args: [--preserve-quotes]
+
+  # Optimize images for size
+  - repo: https://github.com/boidolr/pre-commit-images
+    rev: v1.5.1
+    hooks:
+      - id: optimize-avif
+      - id: optimize-jpg
+      - id: optimize-png
+      - id: optimize-svg
+      - id: optimize-webp
+
+  # Strip EXIF data from images
+  - repo: https://github.com/stefmolin/exif-stripper
+    rev: 0.1.2
+    hooks:
+      - id: strip-exif
diff --git a/README.md b/README.md
@@ -0,0 +1,93 @@
+# hugo-kofi-shortcodes
+
+This is a set of shortcodes to allow easy integration with [Ko-fi](https://ko-fi.com/).
+
+[Live demo on my blog](https://gagor.pro//2024/03/kofi-shortcodes-for-hugo/).
+
+# Installation
+
+1. Clone hugo-kofi-shortcodes repo to your project:
+
+- as submodule (recommended)
+    ```bash
+    cd your-site-location
+
+    git submodule add --depth=1 https://github.com/tgagor/hugo-kofi-shortcodes.git themes/hugo-kofi-shortcodes
+
+    # initialize any uninitialized submodules in the repository
+    # and then recursively update all submodules
+    # to their latest versions
+    git submodule update --init --recursive
+    ```
+- or by just cloning
+    ```bash
+    cd your-site-location
+
+    git clone --depth=1 https://github.com/tgagor/hugo-kofi-shortcodes.git themes/hugo-kofi-shortcodes
+    ```
+
+3. Update blog config:
+
+```yaml
+theme:
+  - YourThemeOfChoice
+  - hugo-kofi-shortcodes
+```
+
+Original theme should be first, followed up by extension.
+
+If you're unable to get it working, check [`exampleSite`](./exampleSite/) directory.
+
+# List of shortcodes
+
+| Animated button                                                              |
+| ---------------------------------------------------------------------------- |
+| `{{</* kofi/button */>}}` or <br/> `{{</* kofi/button color="#13C3FF" */>}}` |
+| `{{</* kofi/button color="#FF5E5B" */>}}`                                    |
+| `{{</* kofi/button color="#434b57" */>}}`                                    |
+
+| Image style 1                                                             |
+| ------------------------------------------------------------------------- |
+| `{{</* kofi/image1 */>}}` or <br/> `{{</* kofi/image1 style="blue" */>}}` |
+| `{{</* kofi/image1 style="grey" */>}}`                                    |
+| `{{</* kofi/image1 style="red" */>}}`                                     |
+| `{{</* kofi/image1 style="green" */>}}`                                   |
+| `{{</* kofi/image1 style="dark" */>}}`                                    |
+
+| Image style 2                                                             |
+| ------------------------------------------------------------------------- |
+| `{{</* kofi/image2 */>}}` or <br/> `{{</* kofi/image2 style="blue" */>}}` |
+| `{{</* kofi/image2 style="red" */>}}`                                     |
+| `{{</* kofi/image2 style="stroke" */>}}`                                  |
+| `{{</* kofi/image2 style="dark" */>}}`                                    |
+
+### Logotypes
+
+| Logos                                                                 |
+| --------------------------------------------------------------------- |
+| `{{</* kofi/logo */>}}` or <br/> `{{</* kofi/logo style="logo" */>}}` |
+| `{{</* kofi/logo style="mug" */>}}`                                   |
+| `{{</* kofi/logo style="pixel" */>}}`                                 |
+
+### Badges
+
+| Badges                                                                 |
+| ---------------------------------------------------------------------- |
+| `{{</* kofi/badge */>}}` or <br/> `{{</* kofi/badge style=white */>}}` |
+| `{{</* kofi/badge style=dark */>}}`                                    |
+| `{{</* kofi/badge style=bg-white */>}}`                                |
+| `{{</* kofi/badge style=bg-dark */>}}`                                 |
+
+### Dynamic widgets
+
+| Widgets                            |
+| ---------------------------------- |
+| `{{</* kofi/floating-button */>}}` |
+| `{{</* kofi/donation-panel */>}}`  |
+
+### Custom images
+
+| Custom images                                                                                         |
+| ----------------------------------------------------------------------------------------------------- |
+| `{{</* kofi/custom height=200 url="https://media.giphy.com/media/kgKFcQk6oa1WIdHNSl/giphy.gif" */>}}` |
+|                                                                                                       |
diff --git a/exampleSite/content/posts/demo.md b/exampleSite/content/posts/demo.md
@@ -0,0 +1,73 @@
+---
+title: Check out demo of all the Ko-fi shortcodes
+date: 2024-03-08
+authors:
+  - tgagor
+---
+
+## Demos
+
+### Animated buttons
+
+Those look nice and have animated mugs, but I saw them being blocked by uBlock Origin.
+
+| Animated button                     | Shortcode                                                                    |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| {{< kofi/button >}}                 | `{{</* kofi/button */>}}` or <br/> `{{</* kofi/button color="#13C3FF" */>}}` |
+| {{< kofi/button color="#FF5E5B" >}} | `{{</* kofi/button color="#FF5E5B" */>}}`                                    |
+| {{< kofi/button color="#434b57" >}} | `{{</* kofi/button color="#434b57" */>}}`                                    |
+
+
+### Static images
+
+| Image style 1                     | Shortcode                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| {{< kofi/image1 >}}               | `{{</* kofi/image1 */>}}` or <br/> `{{</* kofi/image1 style="blue" */>}}` |
+| {{< kofi/image1 style="grey" >}}  | `{{</* kofi/image1 style="grey" */>}}`                                    |
+| {{< kofi/image1 style="red" >}}   | `{{</* kofi/image1 style="red" */>}}`                                     |
+| {{< kofi/image1 style="green" >}} | `{{</* kofi/image1 style="green" */>}}`                                   |
+| {{< kofi/image1 style="dark" >}}  | `{{</* kofi/image1 style="dark" */>}}`                                    |
+
+| Image style 2                      | Shortcode                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| {{< kofi/image2 >}}                | `{{</* kofi/image2 */>}}` or <br/> `{{</* kofi/image2 style="blue" */>}}` |
+| {{< kofi/image2 style="red" >}}    | `{{</* kofi/image2 style="red" */>}}`                                     |
+| {{< kofi/image2 style="stroke" >}} | `{{</* kofi/image2 style="stroke" */>}}`                                  |
+| {{< kofi/image2 style="dark" >}}   | `{{</* kofi/image2 style="dark" */>}}`                                    |
+
+### Logotypes
+
+| Logos                           | Shortcode                                                             |
+| ------------------------------- | --------------------------------------------------------------------- |
+| {{< kofi/logo style="logo" >}}  | `{{</* kofi/logo */>}}` or <br/> `{{</* kofi/logo style="logo" */>}}` |
+| {{< kofi/logo style="mug" >}}   | `{{</* kofi/logo style="mug" */>}}`                                   |
+| {{< kofi/logo style="pixel" >}} | `{{</* kofi/logo style="pixel" */>}}`                                 |
+
+### Badges
+
+| Badges                            | Shortcode                                                              |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| {{< kofi/badge style=white >}}    | `{{</* kofi/badge */>}}` or <br/> `{{</* kofi/badge style=white */>}}` |
+| {{< kofi/badge style=dark >}}     | `{{</* kofi/badge style=dark */>}}`                                    |
+| {{< kofi/badge style=bg-white >}} | `{{</* kofi/badge style=bg-white */>}}`                                |
+| {{< kofi/badge style=bg-dark >}}  | `{{</* kofi/badge style=bg-dark */>}}`                                 |
+
+### Dynamic widgets
+
+| Widgets                      | Shortcode                          |
+| ---------------------------- | ---------------------------------- |
+| {{< kofi/floating-button >}} check left-bottom corner | `{{</* kofi/floating-button */>}}` |
+| {{< kofi/donation-panel >}}  | `{{</* kofi/donation-panel */>}}`  |
+
+### Custom images
+
+You can also use your custom images:
+```go
+{{</* kofi/custom height=200 url="https://media.giphy.com/media/kgKFcQk6oa1WIdHNSl/giphy.gif" */>}}
+```
+
+{{< kofi/custom height=200 url="https://media.giphy.com/media/kgKFcQk6oa1WIdHNSl/giphy.gif" >}}
+
+For inspiration check here:
+* https://more.ko-fi.com/brand-assets
+* https://giphy.com/Kofi_button
diff --git a/exampleSite/hugo.yaml b/exampleSite/hugo.yaml
@@ -0,0 +1,17 @@
+baseURL: 'https://example.org/'
+languageCode: en-us
+title: My New Hugo Site with Ko-fi me shortcodes
+
+theme:
+  - PaperMod # your preferred theme
+  - hugo-kofi-shortcodes
+
+params:
+  # ko-fi config
+  kofi:
+    username: tgagor
+
+menu:
+  main:
+    - name: Demo
+      url: /posts/demo/
diff --git a/layouts/partials/kofi_image.html b/layouts/partials/kofi_image.html
@@ -0,0 +1,7 @@
+<!-- Author: Tomasz Gągor https://github.com/tgagor/hugo-kofi-shortcodes -->
+<!-- Ko-fi Image -->
+<a href='https://ko-fi.com/{{ .user }}' target='_blank'>
+    <img height='{{ .height }}' {{ if .width }}width='{{ .width }}' {{ end }} style='border:0px;height:{{ .height }}px;{{ if .width }}width:{{ .width }}px; {{ end }}'
+        src='{{ .url }}'
+        border='0' alt='{{ .alt_text }}' />
+</a>
diff --git a/layouts/shortcodes/kofi/badge.html b/layouts/shortcodes/kofi/badge.html
@@ -0,0 +1,50 @@
+<!-- Author: Tomasz Gągor https://github.com/tgagor/hugo-kofi-shortcodes -->
+<!-- Ko-fi Image -->
+<!--
+Parameters:
+user - your username from ko-fi.com/username page
+alt_text - alt_text shown when picture can't be downloaded
+height - picture height
+style - there are styles numbered from 1-5 blue, dirty blue, red, green, black
+-->
+
+{{- $user := "" -}}
+{{- with $.Page.Site.Params.kofi.username -}}
+    {{- $user = . -}}
+{{- end -}}
+{{- with .Get "user" -}}
+    {{- $user = . -}}
+{{- end -}}
+{{- if not $user -}}
+    {{- errorf "shortcode kofi/badge: can't determine the Ko-fi username, use 'user' parameter in this shortcode or set it globally in the config.yaml under: `params.kofi.username'" -}}
+{{- end -}}
+
+{{- $alt_text := "Buy Me a Coffee at ko-fi.com" -}}
+{{- with .Get "alt_text" -}}
+    {{- $alt_text = . -}}
+{{- end -}}
+
+{{- $height := "100" -}}
+{{- with .Get "height" -}}
+    {{- $height = . -}}
+{{- end -}}
+
+{{- $width := "271" -}}
+{{- with .Get "width" -}}
+    {{- $width = . -}}
+{{- end -}}
+
+{{- $image := "https://storage.ko-fi.com/cdn/brandasset/kofi_s_tag_white.png" -}}
+{{- $colors := dict "white" "kofi_s_tag_white" "dark" "kofi_bg_tag_dark" "bg-white" "kofi_bg_tag_white" "bg-dark" "kofi_s_tag_dark" -}}
+{{- $keys := slice -}}
+{{- range $k, $_ := $colors -}}
+    {{- $keys = $keys | append $k -}}
+{{- end -}}
+{{- with .Get "style" -}}
+    {{- if not (in $keys .) -}}
+        {{- errorf "shortcode kofi/badge: parameter 'style' can only accept one of: %s" (delimit $keys ", ") -}}
+    {{- end -}}
+    {{- $image = printf "https://storage.ko-fi.com/cdn/brandasset/%s.png" (index $colors .) -}}
+{{- end -}}
+
+{{ partial "kofi_image" (dict "user" $user "alt_text" $alt_text "height" $height "width" $width "url" $image) }}
diff --git a/layouts/shortcodes/kofi/button.html b/layouts/shortcodes/kofi/button.html
@@ -0,0 +1,38 @@
+<!-- Author: Tomasz Gągor https://github.com/tgagor/hugo-kofi-shortcodes -->
+<!-- Ko-fi Button -->
+<!--
+Parameters:
+user - your username from ko-fi.com/username page
+text - text shown on the button
+color - hex color of the button
+-->
+
+{{- $user := "" -}}
+{{- with $.Page.Site.Params.kofi.username -}}
+    {{- $user = . -}}
+{{- end -}}
+{{- with .Get "user" -}}
+    {{- $user = . -}}
+{{- end -}}
+{{- if not $user -}}
+    {{- errorf "shortcode kofi/button: can't determine the Ko-fi username, use 'user' parameter in this shortcode or set it globally in the config.yaml under: `params.kofi.username'" -}}
+{{- end -}}
+
+{{- $text := "Support Me on Ko-fi" -}}
+{{- with .Get "text" -}}
+    {{- $text = . -}}
+{{- end -}}
+
+{{- $color := "#29abe0" -}}
+{{- with .Get "color" -}}
+    {{- $color = . -}}
+{{- end -}}
+
+{{- if not (.Page.Store.Get "hasKofiWidget2") -}}
+{{- .Page.Store.Set "hasKofiWidget2" true -}}
+<script type='text/javascript' src='https://storage.ko-fi.com/cdn/widget/Widget_2.js'></script>
+{{- end -}}
+
+<script
+    type='text/javascript'>kofiwidget2.init('{{ $text }}', '{{ $color }}', '{{ $user }}'); kofiwidget2.draw();
+</script>