Podcast Blog SEO

Create, update and optimise blog posts on podcastalarm.app (Jekyll + GitHub Pages).

Key IDs

• GA4 property: 249905482 (PodcastAlarm.app)
• GSC property: sc-domain:podcastalarm.app
• Site repo: /Users/jonathanwilson/Developer/PodcastAlarm-site (Jekyll, master branch, GitHub Pages)
• Listen Notes API key: in /Users/jonathanwilson/Developer/PodcastAlarm/PodcastAlarm/Services/PodcastAPI.swift (grep for apiKey)
• Image script: PodcastAlarm-site/scripts/fetch-podcast-images.py

Creating a New Blog Post

Step 1: Write the post

File: _posts/YYYY-MM-DD-slug.markdown

markdown
1---
2layout: post
3title: "POST TITLE (2026)"
4categories: Podcast
5featured-image: "/images/blog/charts/100UK2020/kelly-sikkema-1KfV102FCcQ-unsplash.jpg"
6featured-image-alt: "Description"
7description: "UNDER 160 CHARS. Include 2-3 podcast names. Never mention Podcast Alarm."
8permalink: /blog/slug-here
9author: "Jonathan Wilson"
10authorImage: "/images/blog/me.png"
11---
12
13<p>Intro paragraph.</p>
14
15{% include callToActionRow.html %}
16
17<br>
18
19<h3><a class="text-info" href="https://podcasts.apple.com/gb/search?term=Podcast+Name">1. Podcast Name</a></h3>
20<img src="/images/blog/charts/NEWDIR/filename.jpg" alt="Podcast Name podcast artwork" width="100" style="border-radius:12px;float:left;margin:0 15px 15px 0;">
21<p>2-3 sentences. What makes it good, who hosts it, why listen.</p>
22<br style="clear:both;">
23
24<h3><a class="text-info" href="https://podcasts.apple.com/gb/search?term=Podcast+Name+2">2. Podcast Name 2</a></h3>
25<img src="/images/blog/charts/NEWDIR/filename2.jpg" alt="Podcast Name 2 podcast artwork" width="100" style="border-radius:12px;float:left;margin:0 15px 15px 0;">
26<p>Description.</p>
27<br style="clear:both;">

CRITICAL: Every entry MUST have:

1. Apple Podcasts search link on the <h3>
2. <img> tag with the podcast artwork image
3. <br style="clear:both;"> after the <p>

Never write <h3> + <p> without the image — the inline artwork is a core part of every post's design. After fetching images, immediately wire them into the post before deploying.

Step 2: Fetch images

Read the API key from PodcastAPI.swift, then write a JSON file and run the script:

bash
1cd /Users/jonathanwilson/Developer/PodcastAlarm-site
2export LISTEN_NOTES_API_KEY="THE_KEY"
3python3 scripts/fetch-podcast-images.py --podcasts-file podcasts.json --output-dir images/blog/charts/NEWDIR

The podcasts.json format:

json
1[
2  ["Search query for podcast", "explicit-filename.jpg"],
3  ["Another Podcast Host Name", "another-podcast.jpg"]
4]

Always use explicit filenames — similar names like "The Rest Is Politics" / "The Rest Is History" collide when auto-slugified.

Step 3: Check the script output

The script reports NOT FOUND and WRONG MATCH separately. For every NOT FOUND or WRONG MATCH:

• Swap that podcast for a different one that has an image
• Re-run the script
• Repeat until zero failures

Step 4: Verify before deploying

bash
1# Must return nothing (only the featured-image line in frontmatter is OK):
2grep "kelly-sikkema" _posts/YOUR-POST.markdown | grep -v "featured-image"
3
4# Must return nothing (no placeholder references):
5grep "100UK2020" _posts/YOUR-POST.markdown | grep -v "featured-image"

Step 5: Commit and push

bash
1git add _posts/ images/
2git commit -m "Add new blog post: TITLE"
3git push origin master

Live in 1-2 minutes on GitHub Pages.

Post Formats

Article post (layout: post)

Use <h3> + <p> for each entry. Best for SEO — more text content.

Chart/list post (layout: chart)

For large lists (50-100 items). Top 10 get full cards, rest go in image grids.

Top entries: blogPostListItem.html — takes title, content, link, image

{% include blogPostListItem.html
  title="1) Podcast Name"
  content="Description here."
  link="https://podcasts.apple.com/gb/podcast/..."
  image="/images/blog/charts/DIR/filename.jpg"
%}

Grid entries: blogPostTopChartListItem.html in rows of 3

html
1<div class="row">
2  <div class="col-md-4">
3  {% include blogPostTopChartListItem.html
4    title="11) Short Name"
5    content=""
6    link="#"
7    image="/images/blog/charts/DIR/filename.jpg"
8  %}
9  </div>
10  <div class="col-md-4">
11    {% include blogPostTopChartListItem.html
12      title="12) Short Name"
13      content=""
14      link="#"
15      image="/images/blog/charts/DIR/filename.jpg"
16    %}
17  </div>
18  <div class="col-md-4">
19    {% include blogPostTopChartListItem.html
20      title="13) Short Name"
21      content=""
22      link="#"
23      image="/images/blog/charts/DIR/filename.jpg"
24    %}
25  </div>
26</div>

Grid title max: 22 characters after the number prefix. Strip "The", host names, "Podcast", "Show":

• "On Purpose with Jay Shetty" → "On Purpose"
• "The Totally Football Show" → "Totally Football"

Cross-link between posts:

html
1<p>⭐️Featured in <a class="text-info" href="/blog/other-post">Other Post Title</a></p>

Meta Title & Description Rules

Replacing an Existing Post

1. New file with today's date and new slug
2. permalink: /blog/new-slug (evergreen, no year in URL)
3. redirect_from: /blog/old-slug for 301 redirect
4. Change old post's permalink (append -old) to avoid conflict

Analysing SEO Data

Pull GA4 and GSC in parallel:

GA4:  run_report on property 249905482
      - 30 days vs previous 30: totalUsers, sessions, screenPageViews, engagementRate
      - by channel: sessionDefaultChannelGroup
      - by page: pagePath

GSC:  get_performance_overview for sc-domain:podcastalarm.app
      get_search_analytics by query (top 20)
      get_search_analytics by page (top 15)

Quick wins = high impressions + low CTR + good position (< 10). Meta rewrites, not content changes.

Image Sourcing Caveats

1. Listen Notes doesn't have every podcast. BBC Radio 4, niche UK shows often missing. Swap the podcast, don't use a placeholder.
2. First result is often wrong. Script validates but check the WRONG MATCH report. "The Bunker" returned a paintball podcast.
3. Never deploy placeholder images. If image can't be sourced, change the podcast.
4. Verify every image exists, is > 5KB, and is the correct podcast before pushing.

Writing Style

• Write like recommending shows to a friend — not a listicle robot
• No filler ("In today's world...", "It's no secret that...")
• Short paragraphs: 2-3 sentences per entry
• Every entry needs: podcast name, host, what makes it worth listening to