
## Test, trust the data, and optimize your site for better results

In this video, I dive into A/B testing with PostHog to boost newsletter signups on my site. I walk you through my process—from identifying issues with signups, switching email platforms, to experimenting with different UX elements. I'll show you how to set up and run A/B tests, and explain why trusting the data is crucial for making smart, data-driven decisions. If you're a developer or UX enthusiast, this video will help you refine your own website's user experience.

The code for my site is available on github - you can see the Pull Request for the changes associated with this video here: https://github.com/mbifulco/blog/pull/832

## Watch the first two episodes in this series:

1. [Product Analytics for engineers: Debugging a conversion problem on my next.js site](https://mikebifulco.com/posts/debugging-a-conversion-problem-on-my-nextjs-site)
2. [Fixing the bug behind my Conversion Problem](https://mikebifulco.com/posts/fixing-my-conversion-problem)

## Video Timestamps

- 00:00 Introduction and Series Overview
- 00:35 Identifying the Signup Problem
- 00:59 Switching to Resend
- 01:11 Exploring AB Testing
- 01:19 Sponsorship by PostHog
- 02:11 Website Elements and Hypotheses
- 04:07 Implementing AB Tests
- 05:03 Setting Up PostHog Experiments
- 07:20 PostHog Implementation Details
- 08:31 Testing and Analyzing Results
- 10:52 Tell me what you think!

<details>

  <summary>

    <b>Transcript</b>

  </summary>

[00:00:00] **Mike Bifulco:** Hello, and welcome back to tiny improvements. My name is Mike And since we last talked, I've been working on a problem on my website. This is the third video in a series that I'm doing on trying to get people, to sign up for my newsletter.

[00:00:11] If you're new here, I read a weekly newsletter called tiny improvements.

[00:00:13] That is meant for product developers, startup founders, indie hackers, people who are interested in building products. Where I share the things that I've learned, building products that companies like Google and Stripe and Microsoft, and more recently building a venture capital backed startup I'm co-founder of a company called Craftwork. We went through Y Combinator last summer. And so this is my way of giving back. I'm trying to give away the things that I know for free, because I've been really lucky in my career.

[00:00:34] And I want you to be as lucky as I have been. So since you're here, let's talk about where we've been in the first video. I discovered that I had a problem with signups and people weren't subscribing. I was using convert kit for my newsletter at the time and was having some sort of mystery problem with signups.

[00:00:47] So I added a bunch of telemetry to show me when signups were happening and to try and detect failures from that experience, I found that. I was getting some mystery failures with convert kit in my implementation of my newsletter signup form. And that's [00:01:00] what led me to what I did in the second video, which is where I replaced convert kit with Resend.

[00:01:03] So now I use Resend email platform for both sending my newsletters and getting people to sign up for my mailing list. That's been really nice so far. In this video I'm exploring the next thing I wanted to get into, which is AB testing stuff on my site.

[00:01:16] So let's take a look at that and see what that actually means in practice.

## Sponsored by Posthog

[00:01:19] **Mike Bifulco:** Hey, all this video series is sponsored by PostHog. After seeing my first video, they reached out about a sponsorship, which is really cool.

[00:01:25] And frankly, I'm flattered to see it. I was planning on making these videos either way and that's because I really enjoy PostHog. I also really enjoy building products and seeing things improve over time. . I wouldn't take a sponsorship from something that I don't believe in and don't use, I hope you're enjoying this series and I hope you're learning something.

[00:01:39] If you're really into it, it might also be worth giving. PostHog a shot. One of my favorite things about the platform is that they're free tiers, unbelievably generous. You can get a whole lot out of PostHog for free before paying anything to decide if it's worth it for you.

[00:01:50] There's also a self host option. If you want to go that route and PostHog also has a ton of open source software, which means you can have influence over the product itself.

[00:01:58] I think that's really amazing. And the team has been [00:02:00] super responsive so far. So if you want to check it out, go to PostHog dot com slash Mike Bifulco. There'll be a link in the description. It will let them know I sent you and it means a lot to me.

[00:02:09] Thanks so much. I hope you enjoy the rest of the video.

[00:02:11] Okay, this is my site and this is one of the things that I'm interested in testing to see if I can make a difference in the amount of people signing up.

[00:02:17] When you visit my site, read one of my newsletters or any of the articles on my site. There's a bunch of things that are made available at the top of the pages, a cover image and a title things you're probably used to seeing, I have this nice dynamic. Table of contents, which is really helpful I also record audio versions of some posts, which is why we see this podcast embedded here. if we scroll through the post, when you get towards the end of it, a couple of things happen.

[00:02:36] This pop-up, that just flew in from the left is a thing called polite pop. This is where the first call to action typically comes for someone to subscribe to my newsletter. I've got a couple of hypotheses on how we can do better here. What I want to do is test the copy.

[00:02:48] That's rendered here to see if there's maybe a different treatment, that we can show. To people to get them more compelled to sign up. I might also choose to remove this. It kind of is just an ag and I think people are really well-trained to just dismiss pop-ups and [00:03:00] try and get them out of their face.

[00:03:01] And it's a little bit of a rude experience while you're on a site. I see loads of people coming to my site and clicking this. No thanks button. I've got tons of telemetry on that. That may not be long for this world.

[00:03:09] The other thing that I see, and I think this is worth testing straight away is at the bottom of each post.

[00:03:14] I have this giant banner, which is this big striking thing that says ship products that matter. And I really like this. This is something I workshopped for awhile, trying to come up with a slogan or phrase, something that was sort of attention grabbing. That's supposed to give people a reason to sign up.

[00:03:28] However, I think what I've done here is I built something that is so different from everything else. That's that seen on my site that. By the time you get down here, as you scroll down and you get this great big dark banner that appears, it's pretty obvious that the article is over and then I'm not giving you any more value here. And so what I want to test is if I can replace this with something that's a little more subtle.

[00:03:47] So maybe not a giant banner like this, but something that says, Hey, I write this cool newsletter. I think you might like it. Please subscribe. And maybe Tiki into people's psychology a little bit to keep them reading on the page. watching back some replays of people visiting the site. [00:04:00] It's pretty common to see someone get to about here and go away.

[00:04:02] And if they leave before they get down here, I've lost. So. we're going to try a couple of things here and that's. Where AB testing comes in.

## A-B Testing in PostHog

[00:04:08] an AB test is exactly what it sounds like. I have version a version B and sometimes C D E F a number of different versions of one bit of user experience that I want to test against each other to see how they perform. The idea here is to see that if I do this versus that is one going to get me more people signing up for my newsletter or not.

[00:04:24] **Mike Bifulco:** And we can kind of test some hypothesis from there. Now there's some really important statistics involved in how this works. What I really like is that when you collect data, the math will tell a story. And if you're willing to trust the math and listen to what the statistics say, you can probably make a good data driven decision to move yourself from doing well, to doing better and incremental change over time will do really well.

[00:04:46] But you have to be comfortable with trusting what the statistics say. And let me be the first to tell you that there's a lot to learn about that, and it can be really counter-intuitive. I am far from a statistics expert. I have learned a lot of mathematics in my life.

[00:04:57] You have to learn to trust the statistics. [00:05:00] And so that's what we're going to try to do here. Let me get off my high horse. Let's talk about this. So this is my first experiment is called newsletter banner treatments. So you give it a name, which is a human readable thing, and then our feature flag key.

[00:05:10] So this is the key that we'll use programmatically to make decisions based on this experiment. So I gave it newsletter banner treatments as the key. The description here again is a human readable thing. It's meant for me when I go review these later on to see what this experiment was all about.

[00:05:23] So I may fill this in with more detail, but the idea is I want to test different UX presentations of the newsletter banner that appears at the bottom of articles. To see which one performs best.

[00:05:32] By default PostHog will give you a control, which is the fallback value. So the control is meant to be in scientific method speak.

[00:05:39] That means the thing that we know how it performs and the baseline for the experience right now, that's that big dark banner that I show on my site that I was just showing you that people sort of. Seem to scatter away from. I'm running two tests against that in this case. So I'm going to test a simple implementation and a hero implementation. Those are bits of UI that I've built alternatives for.

[00:05:58] And I'll show you what they look like. [00:06:00] So if I come through and I hit, continue on this experiment, we'll see that PostHog does a little bit of thinking. And it goes to do some give me some numbers on roughly what this would look like. And what I want to check is my newsletter subscribed event.

[00:06:11] So I'm hoping to see more of these newsletter subscribed things happening. With one variant of this versus the other, they'll probably all perform slightly differently. We're going to pick the one that wins out of the three. So. I've picked the event that I want to use. If I go to the next page here, what I get is the goal for the experiment.

[00:06:28] So this now shows me everything in one view. What it's saying at the very top is this is a draft. I haven't actually started it yet. By results are not significant, meaning I haven't collected enough data to make a decision. And the feature flags name is here.

[00:06:39] Down here, we get implementation details from PostHog, which is literally code snippets that you can use in your application. So you can switch through these and see what they look like.

[00:06:47] There's react native there's no, there's Ruby, all kinds of stuff in here. What's really cool is they show you exactly how to do this. So you load the feature flag using the feature flags name. If you have a user ID, like an email address, if someone's logged in, you can pass that [00:07:00] into, they always get a consistent experience per user. And then you make a decision based on what comes back. So the feature flag will say for this person render a simple one. It might come back and say for this person render a hero one and you do different things based on that. So what I'll do is I'll hit launch on this thing, It'll sort of thing for a second and go live and I'll, show you what the implementation looks like, next.

[00:07:20] Okay, implementation time. So I'm using post hogs library called PostHog JS.

[00:07:26] Thanks sports, some really nice react components, which I'm using in this implementation here. So this experiment name, newsletter, banner treatments is what we just saw on the site. These are the three different experiment variants.

[00:07:35] So these are the things that the experiment will tell me to render for different users. And we'll collect data on that. And I'm using a thing called PostHog feature, which is a react component exported by post hog, which takes in the name of the flag. As well as the part of the experiment to match.

[00:07:50] So what this is saying is we're going to do this with the newsletter experiment. So if it comes back and says control, we're going to render this thing, the fancy component, which is the newsletter banner that's currently shown on [00:08:00] the site with the dark background.

[00:08:01] I've created two other variants. The simple one here is based on a fairly standard tailwind component library. And this one called hero is one that I was using on other pages on my site, but wasn't consistently showing on the bottom of articles.

[00:08:13] now I'm taking all three of these things. And for about a third of users, I'll show each one of these and we'll track. How many of them convert to newsletter subscriptions over the next. Week or so, and we'll see what comes back.

[00:08:23] Next thing to see is what this looks like in the browser, because PostHog also provides some tools for you to be able to poke around with these and make sure it works well before you roll it out to your users.

## PostHog's A-B Testing tools in the browser

[00:08:31] **Mike Bifulco:** All right back here on post-talk and here's what I want to show you.

[00:08:35] from any page on PostHog, you can get to this handy thing called toolbar. If I click into this, this gives me the ability to launch a PostHog specific toolbar within the context of my site. So it doesn't really fancy injection of content. And it renders PostHog using what I believe is a Chrome extension.

[00:08:50] And so if I click on this, it's going to load my local host, which I've told is where I'm running my site. This is what the tool bar looks like.

[00:08:55] Typically you'll see it. Like this, when it first comes up and we're really interested in this [00:09:00] feature flags. Functionality here. So there's a bunch of things here. You can do actions and heat maps and all kinds of stuff like that. But let's take a look at feature flags first. I'm going to navigate to one of my newsletters, the most recent one, we were just checking this out and I'm going to scroll to the bottom and I'm going to go to this feature flags thing here and already something looks different, This is not the banner that was showing before. And this is a sign that my experiment is working. you can see here, I can manually override the experiments that I'm seeing personally in development.

[00:09:25] And as I toggle through these, I get three different presentations. this one might look familiar. This is the hero one I had before. This is the simple implementation that I wanted to take a look at. And then here's the control implementation. the important thing to test here is we're trying to test things that could produce the same output against each other. When users come to this page, I want to make sure they can submit this form and get the output that I want from each of them, which is that newsletter subscribed event.

[00:09:46] So from this control one, This is a newsletter subscription form. First name and email address is exactly what we want to see the simple form, same thing. First name, email address, and then the hero form. Once again, first name and email address. So. [00:10:00] All the primitives are here. I have three different variants of this thing.

[00:10:03] The next thing to do is to set this live and just record some traffic for awhile. there are some statistical minimums. We have to get a certain amount of users interacting with each one of these, to be able to say whether it worked or not. And the next part is just waiting. So we're going to spin this up on PostHog.

[00:10:17] We're going to collect some data over the next week or two, however long it takes, and then we'll start to make some decisions based on that and go into the next step from there.

[00:10:23] So that's all there is to it. It's a little bit of implementation. It's a little bit of work to set up the three different variants, but now I need to trust the statistics. I need to listen to what comes back from post-hoc as the experiment runs. And tweak my site design based on the data that comes back. My guess is it'll probably take about two weeks for this to come back with meaningful results. But lucky for me, I can run a couple of experiments in parallel, as long as the two different experiments don't interfere with each other. I can probably still draw a valid conclusion from it. So over the next week or so I'll watch this and I'll see what happens.

## What do you think?

[00:10:52] **Mike Bifulco:** If you've been hanging on for the whole series so far, I'm really curious what you think of this.

[00:10:55] Is this something you would find useful for your site? Do you have an idea of experiments you'd like to run? Do you have [00:11:00] questions about this stuff?

[00:11:01] I spent a bunch of my career working in design and user experience. So this sort of thing is a process that I really enjoy, but I can understand that it might be frustrating too, especially if you just want to get to results.

[00:11:10] If you have questions for me, feel free to drop them in the comments. . Your ideas are always welcome here. There's no criticism too big or too small. I'd love to hear what you're thinking. Thanks so much. My name is Mike bi-fold co this is tiny improvements and we'll catch up for the next one.

</details>


Unlocking A/B Testing with PostHog: Improving Newsletter Signups

Test, trust the data, and optimize your site for better results

Watch the first two episodes in this series:

PostHog's A-B Testing tools in the browser


## I publish a newsletter called Tiny Improvements

[My little newsletter](https://mikebifulco.com/newsletter) is all about making small, incremental improvements to your work and home life, especially if you're building a product or company. I've been publishing it for a while now, and I've been using ConvertKit to manage my subscribers and send out the newsletter.

<Aside>

Note: This is a follow-up to my [previous post on using ConvertKit with Remix](https://mikebifulco.com/posts/publish-your-newsletter-with-convertkit-api-remix). If your site is built using [**Remix.run**](https://remix.run), you'll probably want to head over there.

</Aside>

In this post, we'll go over how I use the ConvertKit API to publish a newsletter page for a site built with [Next.js](https://nextjs.org).

## Publish past issues to grow your newsletter

I recently started publishing back-issues of my [newsletter](https://mikebifulco.com/newsletter) to my site, so that I can share them as evidence of the type of writing I do. In addition to being SEO-indexable, it allows me to share the newsletter with people who aren't subscribed to it, with a link to subscribe at the bottom of each issue.

I wanted to explore a way to make _my_ process incrementally better, by using the [ConvertKit API](https://developers.convertkit.com/) to automate the publishing process with the same workflow that I use to send newsletters to subscribers.

## Using the ConvertKit API to publish newsletters to a Next.js site

Setting up an automated newsletter page is fairly simple, at least in theory:

1. Write newsletters and send them, using ConvertKit's broadcast features (for the sake of this post, we'll use the term "newsletter" and "broadcast" somewhat interchangeably).
2. Use the ConvertKit API's list-broadcasts endpoint to query for every published broadcast, to populate a newsletter index page
3. For each published broadcast, use the ConvertKit API to get the details of that broadcast, and then render the content of that broadcast on a page.
4. For SEO purposes, add each published newsletter page to `sitemap.xml`, with all the appropriate metadata.

To get newsletters from the ConvertKit API, I set up 2 helper functions in `/src/utils/convertKit.js`. First is `getNewsletter()`, which takes a broadcast ID and returns the details of that broadcast.

```js
export const getNewsletter = async (broadcastId) => {
  const res = await fetch(
    `https://api.convertkit.com/v3/broadcasts/${broadcastId}?api_secret=${CONVERTKIT_API_SECRET}`
  );

  // rename "broadcast" to "newsletter" for consistency
  const { broadcast: newsletter } = await res.json();

  return newsletter;
};
```

The second is `getAllNewsletters()`, which returns a list of all published broadcasts. In its simplest form, this function looks like this:

```js
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();

  // rename "broadcasts" to "newsletters" for consistency
  const { broadcasts: newsletters } = data;

  return newsletters;
};
```

<Aside type="warning">

We are using an environment variable to supply the variable `CONVERTKIT_API_SECRET` - it is **super important** to keep this value secret, and not share it on the client-side of your app.

</Aside>

### Keeping your ConvertKit API Secret key safe on Next.js sites

For this example, we're using `CONVERTKIT_API_SECRET` environment variable only on the server-rendered parts of our site, because we _do not want it to be exposed to the client_. To make this value accessible only server-side, add it to a file called `.env` or `.env.local`, according to [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#loading-environment-variables). **Make sure you add `.env` and `.env.local` to your [`.gitignore` file](https://mikebifulco.com/posts/gitignore-io-is-great), so you don't accidentally commit it to your repository.**

Importantly, this environment variable should only be exposed server-side, because we _didn't_ name it with a `NEXT_PUBLIC_` prefix - to read more about using environment variables to web clients, check out [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser).

### Rendering the newsletter index page

Now that we have a way to get a list of all published newsletters, we can use that to render a page with a preview of each past issue. I created a new file called `/src/pages/newsletter/index.js` to render the newsletter index page.

On this page, we use `getStaticProps` to fetch our list of newsletters on the server, and then pass them to render function, to display a list of links to each newsletter page.

<small>

_note: I stripped out the styling/presentation code from this example to keep
it focused on data loading logic._

</small>

```jsx
import { Link } from 'next/link';
import { getAllNewsletters } from '../../utils/convertKit';

import slugify from '../../utils/slugify';

export const getStaticProps = async () => {
  const newsletters = await getAllNewsletters();

  return {
    props: {
      newsletters,
    },
  };
};

const NewsletterIndexPage = ({ newsletters }) => {
  return (
    <>
      <h1>All Newsletters</h1>
      <ul>
        {newsletters?.map((newsletter) => (
          <li key={newsletter.id}>
            <Link href={`/newsletter/${slugify(newsletter.subject)}`}>
              {newsletter.subject} - {formatDate(newsletter.published_at)}
            </Link>
          </li>
        ))}
      </ul>
    </>
  );
};

export default NewsletterIndexPage;
```

You may have noticed that I'm also using a helper function called `slugify`, which uses the npm package `slugify`. This function takes a string and returns a skewer-case-version-of-it, which is useful for creating browser-friendly URLs from strings.

```js
import makeSlug from 'slugify';

export const slugify = (string) => {
  return makeSlug(string, {
    replacement: '-',
    remove: /[\[\],?*+~.()'"!:@]/g,
    strict: true,
    lower: true,
  });
};

export default slugify;
```

This is an optional step that caused me a fair bit of heartache - the easiest way to link to individual newsletter pages is to use the broadcast ID, but I wanted to use a more human-readable URL, so I used `slugify` to create a URL-friendly version of the newsletter subject.

The downsides of this approach are:

- each newsletter _must_ have a unique URL
- there's not a way to efficiently map a URL to a broadcast ID, so we have to iterate over all broadcasts to find the one that matches the URL (which you'll see in the next section)

For now, I can live with this approach, since this computation is done once during build time, and until I have hundreds of newsletters, it shouldn't be too big of a performance hit.

### Rendering a single newsletter page

Now that we have a page listing all published newsletters, we need to create a page template to render a single newsletter. I created a new file called `/src/pages/newsletter/[subject].js` to render the newsletter index page (note, once again, that presentation and styling code is removed here for simplicify):

```jsx
import { useEffect } from 'react';
import {
  broadcastTemplateParse,
  getAllNewsletters,
} from '../../utils/convertKit';
import slugify from '../../utils/slugify';

export const getStaticPaths = async () => {
  const newsletters = await getAllNewsletters();

  return {
    paths: newsletters.map((newsletter) => ({
      params: {
        subject: slugify(newsletter.subject),
      },
    })),
    fallback: false,
  };
};

export const getStaticProps = async (context) => {
  const newsletters = await getAllNewsletters();

  const { subject } = context.params;
  const slug = slugify(subject);

  const newsletter = newsletters.find(
    (newsletter) => slugify(newsletter.subject) == slug
  );

  return {
    props: {
      newsletter,
    },
  };
};

const SingleNewsletterPage = ({ newsletter }) => {
  const { subject } = newsletter;

  return (
    <>
      <h1>{subject}</h1>
      <div
        dangerouslySetInnerHTML={{
          __html: broadcastTemplateParse({ template: newsletter.content }),
        }}
      />
    </>
  );
};

export default SingleNewsletterPage;
```

The `getStaticPaths` function is used to generate a list of all possible URLs that should be pre-rendered. In this case, we're using the `getAllNewsletters` function to fetch a list of all published newsletters, and then using the `slugify` function to create a URL based on the newsletter's subject.

The `getStaticProps` function is used to fetch the data for a single newsletter, based on the URL. We use the `getAllNewsletters` function to fetch a list of all published newsletters, and then use `newsletters.find()` to look for the newsletter whose subject line matches the URL for the current page when run through `slugify`. This uses a JavaScript API called [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), which is used to find single item in an array that matches a condition.

#### Render the body using dangersoulySetInnerHTML

To render the contents of the newsletter, we are using a scary-looking React API pattern - `dangerouslySetInnerHTML`. This is a [React API](https://reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml) that allows you to render HTML that you have received from an API, and is generally considered a security risk. However, in this case, we are using it to render HTML that we have generated ourselves, and we are at least somewhat confident that it is safe to render. Generally speaking, this is a technique that shouldn't be used unless you are confident that the HTML you are rendering is safe.

#### Helper functions for displaying ConvertKit newsletter content

We're also using 2 helper functions, which are defined in `/src/utils/convertKit.js`:

```js
import { Liquid } from 'liquidjs';
const engine = new Liquid();

export const broadcastTemplateParse = ({ template, data }) => {
  const t = template.replaceAll('&quot;', '"');
  const res = engine.parseAndRenderSync(t, data);
  return res;
};

export const newsletterHasValidThumbnail = (newsletter) => {
  const { thumbnail_url: thumbnailUrl } = newsletter;
  if (!thumbnailUrl) return false;
  if (thumbnailUrl.startsWith('https://functions-js.convertkit.com/icons'))
    return false;
  return true;
};
```

The `newsletterHasValidThumbnail` function is a helper function that checks if the newsletter has a valid thumbnail image. ConvertKit provides a default thumbnail image for all newsletters, but you can also upload your own, by adding an image to your newsletter's body. This function checks if the thumbnail is the default image, and if so, returns `false` so we can skip rendering it.

The `broadcastTemplateParse` function is a helper function that takes a newsletter template and parses it with the [Liquid](https://shopify.github.io/liquid/) templating language. This is how ConvertKit allows you to customize the HTML of your newsletter, and use dynamic data like the subscriber's name, or the date the newsletter was sent.

**An important caveat:** There are _lots_ of little cases where this might not work perfectly, due to all of the amazing things you can do with Liquid in ConvertKit. At the moment, my newsletter uses fairly basic liquid customization - this may not do the trick for you if you're using more advanced features. Please test your implementation thoroughly!

### Adding more detail to the index page

At the time of writing this post, ConvertKit's v3 API is in "active development" - and as such, it's likely not feature complete. For example, the [current API for list-broadcasts](https://developers.convertkit.com/#list-broadcasts) provides a minimal amount of data about each broadcast:

```bash
curl https://api.convertkit.com/v3/broadcasts?api_secret=<your_secret_api_key>
```

```json
{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
```

Since we want to create an index page that shows a thumbnail for each newsletter, we need to query the API for more information about each newsletter. At the moment, the best way to do this is to query the API for each newsletter individually. It's not ideal, since we need to send an API call for each newsletter shown on the index page, but I'm hoping that with a bit of feedback, ConvertKit will add more data to the list-broadcasts API endpoint.

We already have a function to query the API for a single newsletter (remember `getNewsletter` from earlier?), so we can use that to query the API for each newsletter on the index page.

#### Filter out un-published newsletters

The list-broadcasts endpoint also doesn't currently return whether or not a given broadcast was _published_ yet - which means that if you draft a future broadcast on your ConvertKit dashboard, it will still be returned by the list API. I don't want to share these yet-to-be-sent newsletters on any of my sites, so we'll add some logic to `getAllNewsletters` to filter out any newsletters that haven't been published yet.

#### Don't render newsletters with duplicate subject lines

There are some cases where I send the same newsletter multiple times, with the same subject line, to different audiences - usually because I've forgotten to include some details in the original broadcast. This results in multiple broadcasts with essentially the same content. I don't want to show these on my site, so I added some logic to deduple any newsletters that have the same subject line, displaying only the most recent one (which should be the most correct, in theory).

This is the updated code for `getAllNewsletters` in `convertKit.js`:

```jsx
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();
  const { broadcasts } = data;

  // get details for each individual newsletter
  const newsletters = await Promise.all(
    broadcasts.map((broadcast) => getNewsletter(broadcast.id))
  );

  // hackish dedupe here - sometimes we publish a newsletter a _second_ time as a correction, or to a different audience.
  // In those cases, they should always have the same subject. We're using subject as a way to deduplicate newsletters in that case
  const dedupedBySubject = {};

  // return only newsletters that have been published, and sort by most recent to oldest
  newsletters
    .filter((newsletter) => !!newsletter.published_at)
    .sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
    .forEach((newsletter) => {
      // the first one we encounter in this order will be the newest, so if there's one already we don't make any changes to the object map
      if (!dedupedBySubject[newsletter.subject])
        dedupedBySubject[newsletter.subject] = newsletter;
    });

  let nls = [];
  // iterate over the map we have of subject->newsletter, and push into a fresh array, which we'll return
  for (let subject in dedupedBySubject) {
    nls.push(dedupedBySubject[subject]);
  }

  return nls;
};
```

And with that, our basic implementation is complete - we've created a `/newsletter` page that shows a list of all of our newsletters, with a thumbnail image for each one. We've also added a `/newsletter/[subject]` page that shows the full content of a given newsletter.

## Next steps

There are a few things I'd like to add to this implementation in the future:

- I'm unhappy with the bottleneck I've created for myself using `slugify` on the subject line to create the URL slug. I'd like to find a more efficient way to do this. A reasonable fallback for now might be to use the `BroadcastId` as the slug instead of the subject line, but those aren't human-readable.
- This implementation presents some challenges for SEO - getting newsletter entries to show up in my site's `sitemap.xml` is currently done at build time, which means that new newsletters won't show up in the sitemap until I rebuild the site. In the future, I'll either need to generate the sitemap dynamically, or implement [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration) so that new newsletters are added to the sitemap as soon as they're published.
- I'm pretty diligent about [embedding opengraph metadata](https://mikebifulco.com/posts/reset-your-open-graph-embeds-on-linkedin-twitter-facebook) on the pages on my site, including images and excerpts from the article to use as previews on sites like twitter and LinkedIn. This implementation makes that tricky, as determining _which_ image to use as the cover for a given newsletter is a bit of a challenge. Right now I'm using the first image within a newsletter. I'm not sure what the best solution is here, but I'm open to suggestions!

## Wrap-up

I hope this post has been helpful to you, and that you've learned something new about how to use ConvertKit's API to create a custom newsletter index page for your Next.js site. I'd also love it if you checked out Tiny Improvements, my little newsletter about making better products and a better life - [mikebifulco.com/newsletter](https://mikebifulco.com/newsletter).

If you have any questions, or if you've found a bug in my code, please feel free to reach out to me on Twitter [@irreverentmike](https://twitter.com/irreverentmike)!


Growth hack: Publish newsletters to your Next.js site with ConvertKit API

I publish a newsletter called Tiny Improvements

Publish past issues to grow your newsletter

Using the ConvertKit API to publish newsletters to a Next.js site

Keeping your ConvertKit API Secret key safe on Next.js sites

Render the body using dangersoulySetInnerHTML

Helper functions for displaying ConvertKit newsletter content

Don't render newsletters with duplicate subject lines


## I publish a newsletter called Tiny Improvements

[My little newsletter](https://mikebifulco.com/newsletter) is all about making small, incremental improvements to your work and home life. I've been publishing it for over a year now and I've learned a lot about how to make it better.

It's a great way to share less-formal insights with the people who have given me access to their inbox - a privilege which I don't take lightly. It also helps me keep my writing skills sharp, and it's a great way to get direct feedback on my ideas.

Although the audience for my newsletter has been growing, and recently hit [some milestones](https://twitter.com/irreverentmike/status/1569796408043253760), I realized that I had quite a bit of great writing that went out once, via email, and was never seen again. I wanted to make it easier for people to find and read my past newsletter content without subscribing, as way to show the value it provides. I also wanted to take advantage of the [SEO benefits](https://mikebifulco.com/posts/seo-tools-for-new-web-projects) of having past issues of my newsletter content indexed by search engines.

In this post, we'll go over how I use the ConvertKit API to publish a newsletter page for a site built with [Remix](https://remix.run).

## Improve discoverability by publishing past issues

I have a second, important use case for publishing newsletters online. I also maintain my wife's website - [primaryfocus.tv](https://primaryfocus.tv) - which she uses to promote her business and YouTube channel (go [subscribe](https://youtube.com/c/primaryfocus)!).

Primary Focus has a newsletter, and I wanted to make it easy for her to publish her newsletter to her website as well. In fact, I wanted to give her a way to get her newsletter on her website with zero effort - and I was pleased to find that I could do that with the [ConvertKit API](https://developers.convertkit.com/).

Ideally, the workflow should look like this: newsletters are drafted and published in ConvertKit, and, once sent to her subscribers, automatically published to the website as well. This way, she can focus on writing and sending her newsletter, without adding an additional workflow to update her site.

Her site is built with Remix, so this post will go over the details of implementation for publishing past ConvertKit newsletters to a remix site, using their API.

## Using the ConvertKit API to publish newsletters to a Remix site

Setting up an automated newsletter page is fairly simple, at least in theory:

1. Write newsletters and send them, using ConvertKit's broadcast features (for the sake of this post, we'll use the term "newsletter" and "broadcast" somewhat interchangeably).
2. Use the ConvertKit API's list-broadcasts endpoint to query for every published broadcast, to populate a newsletter index page
3. For each published broadcast, use the ConvertKit API to get the details of that broadcast, and then render the content of that broadcast on a page.

To get newsletters from the ConvertKit API, I set up 2 helper functions. First is `getNewsletter()`, which takes a broadcast ID and returns the details of that broadcast.

```js
export const getNewsletter = async (broadcastId) => {
  const res = await fetch(
    `https://api.convertkit.com/v3/broadcasts/${broadcastId}?api_secret=${CONVERTKIT_API_SECRET}`
  );

  // rename "broadcast" to "newsletter" for consistency
  const { broadcast: newsletter } = await res.json();

  return newsletter;
};
```

The second is `getAllNewsletters()`, which returns a list of all published broadcasts. In its simplest form, this function looks like this:

```js
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();

  // rename "broadcasts" to "newsletters" for consistency
  const { broadcasts: newsletters } = data;

  return newsletters;
};
```

<Aside type="warning">

We are using an environment variable to supply the variable `CONVERTKIT_API_SECRET` - it is **super important** to keep this value secret, and not share it on the client-side of your app.

</Aside>

### Keeping your ConvertKit API Secret key safe on Remix sites

Remix provides a has a handy filename convention to ensure certain code _only_ runs serverside - any file that ends in `.server.ts` (for TypeScript) and `.server.js` (for JavaScript) will only be run on the server. This is perfect for keeping our ConvertKit API secret safe. I created a file called `/app/lib/util/convertkit.server.js` with the two functions above, to make sure to only ever access the secret key in there.

### Rendering the newsletter index page

Now that we have a way to get a list of all published newsletters, we can use that to render a page with a preview of each past issue. I created a new file called `/app/routes/newsletter/index.jsx` to render the newsletter index page.

<small>

_note: I stripped out the styling/presentation code from this example to keep
it focused on data loading logic._

</small>

```jsx
import { useLoaderData } from '@remix-run/react';

import { getAllNewsletters } from '~/lib/util/convertKit.server';
import { NewsletterListItem, NewsletterCTA } from '~/components';

export const loader = async ({ params, request }) => {
  return {
    newsletters: await getAllNewsletters(),
  };
};

const NewsletterListPage = () => {
  const { newsletters } = useLoaderData();

  return (
    <>
      <h1>Read past newsletters</h1>
      {newsletters.map((newsletter) => (
        <NewsletterListItem newsletter={newsletter} key={newsletter.id} />
      ))}

      {/* make sure to add a "hey please subscribe to the newsletter" widget to this page! */}
      <NewsletterCTA />
    </>
  );
};

export default NewsletterListPage;
```

This is a fairly standard implementation, if you're familiar with Remix. We use the loader pattern to fetch the list of newsletters, and pass them to the render function for the component with the `useLoaderData()` hook. We then render a list of `NewsletterListItem` components, which shows a header image and title for each newsletter, along with a link to the page for that specific newsletter.

### Rendering a single newsletter page

Now that we have a page listing all published newsletters, we need to create a page template to render a single newsletter. I created a new file called `/app/routes/newsletter/$id.jsx` to render the newsletter index page (note, once again, that presentation and styling code is removed here for simplicify):

```jsx
import { useLoaderData } from '@remix-run/react';
import {
  broadcastTemplateParse,
  newsletterHasValidThumbnail,
} from '~/lib/util/convertKit';
import NewsletterCTA from '~/components';
import config from '~/config';

import { getNewsletter } from '~/lib/util/convertKit.server';

// render meta tags on page for SEO
export const meta = ({ data }) => {
  const { newsletter, canonical } = data;
  const publishedAt = new Date(newsletter.published_at);

  const description = `Primary focus newsletter: ${
    newsletter.subject
  }, published on ${publishedAt.toLocaleDateString()}`;

  return {
    description,
    title: newsletter.subject
      ? `${newsletter.subject} - ${config.meta.title}`
      : config.meta.title,
    'og:image': newsletterHasValidThumbnail(newsletter)
      ? newsletter.thumbnail_url
      : null,
    'og:type': 'article',
    'og:title': newsletter.subject,
    'og:description': description,
    'og:url': canonical,
    'twitter:card': 'summary_large_image',
  };
};

export const loader = async ({ params, request }) => {
  const { id } = params;
  const newsletter = await getNewsletter(id);

  return { newsletter };
};

const NewsletterPage = () => {
  const { newsletter } = useLoaderData();

  const publishedAt = new Date(newsletter.published_at);
  return (
    <>
      <h1>{newsletter.subject}</h1>
      <p className="publish-date">{publishedAt.toLocaleDateString()}</p>
      <div
        dangerouslySetInnerHTML={{
          __html: broadcastTemplateParse({ template: newsletter.content }),
        }}
      />
      <NewsletterCTA />
    </>
  );
};

export default NewsletterPage;
```

Once again, we use the loader pattern to query the ConvertKit API for details about this specific newsletter, and pair that with `useLoaderData()` to provide that information to the page render function. We also use the `meta` function pattern to render meta tags for SEO purposes - you can read more about that in the [Remix docs](https://remix.run/docs/en/v1/api/conventions#meta).

#### Render the body using dangersoulySetInnerHTML

To render the contents of the newsletter, we are using a scary-looking React API pattern - `dangerouslySetInnerHTML`. This is a React API that allows you to render HTML that you have received from an API, and is generally considered a security risk. However, in this case, we are using it to render HTML that we have generated ourselves, and we are at least confident that it is somewhat safe to render. Generally speaking, this is a technique that shouldn't be used unless you are confident that the HTML you are rendering is safe.

#### Helper functions for displaying ConvertKit newsletter content

We're also using 2 helper functions, which are defined in `/app/lib/util/convertKit.js` (note that these are **not** in `convertkit.server.js`, since we need them on the client side):

```js
import { Liquid } from 'liquidjs';
const engine = new Liquid();

export const broadcastTemplateParse = ({ template, data }) => {
  const t = template.replaceAll('&quot;', '"');
  const res = engine.parseAndRenderSync(t, data);
  return res;
};

export const newsletterHasValidThumbnail = (newsletter) => {
  const { thumbnail_url: thumbnailUrl } = newsletter;
  if (!thumbnailUrl) return false;
  if (thumbnailUrl.startsWith('https://functions-js.convertkit.com/icons'))
    return false;
  return true;
};
```

The `newsletterHasValidThumbnail` function is a helper function that checks if the newsletter has a valid thumbnail image. ConvertKit provides a default thumbnail image for all newsletters, but you can also upload your own, by adding an image to your newsletter's body. This function checks if the thumbnail is the default image, and if so, returns `false` so we can skip rendering it.

The `broadcastTemplateParse` function is a helper function that takes a newsletter template and parses it with the [Liquid](https://shopify.github.io/liquid/) templating language. This is how ConvertKit allows you to customize the HTML of your newsletter, and use dynamic data like the subscriber's name, or the date the newsletter was sent.

**An important caveat:** There are _lots_ of little cases where this might not work perfectly, due to all of the amazing things you can do with Liquid in ConvertKit. At the moment, my newsletter uses fairly basic liquid customization - this may not do the trick for you if you're using more advanced features. Please test your implementation thoroughly!

### Adding more detail to the index page

At the time of writing this post, ConvertKit's v3 API is in "active development" - and as such, it's likely not feature complete. For example, the [current API for list-broadcasts](https://developers.convertkit.com/#list-broadcasts) provides a minimal amount of data about each broadcast:

```bash
curl https://api.convertkit.com/v3/broadcasts?api_secret=<your_secret_api_key>
```

```json
{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
```

Since we want to create an index page that shows a thumbnail for each newsletter, we need to query the API for more information about each newsletter. At the moment, the best way to do this is to query the API for each newsletter individually. It's not ideal, since we need to send an API call for each newsletter shown on the index page, but I'm hoping that with a bit of feedback, ConvertKit will add more data to the list-broadcasts API endpoint.

We already have a function to query the API for a single newsletter (remember `getNewsletter` from earlier?), so we can use that to query the API for each newsletter on the index page.

#### Filter out un-published newsletters

The list-broadcasts endpoint also doesn't currently return whether or not a given broadcast was _published_ yet - which means that if you draft a future broadcast on your ConvertKit dashboard, it will still be returned by the list API. I don't want to share these yet-to-be-sent newsletters on any of my sites, so we'll add some logic to `getAllNewsletters` to filter out any newsletters that haven't been published yet.

#### Don't render newsletters with duplicate subject lines

There are some cases where I send the same newsletter multiple times, with the same subject line, to different audiences - usually because I've forgotten to include some details in the original broadcast. This results in multiple broadcasts with essentially the same content. I don't want to show these on my site, so I added some logic to deduple any newsletters that have the same subject line, displaying only the most recent one (which should be the most correct, in theory).

This is the updated code for `getAllNewsletters` in `convertKit.server.js`:

```jsx
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();
  const { broadcasts } = data;

  // get details for each individual newsletter
  const newsletters = await Promise.all(
    broadcasts.map((broadcast) => getNewsletter(broadcast.id))
  );

  // hackish dedupe here - sometimes we publish a newsletter a _second_ time as a correction, or to a different audience.
  // In those cases, they should always have the same subject. We're using subject as a way to deduplicate newsletters in that case
  const dedupedBySubject = {};

  // return only newsletters that have been published, and sort by most recent to oldest
  newsletters
    .filter((newsletter) => !!newsletter.published_at)
    .sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
    .forEach((newsletter) => {
      // the first one we encounter in this order will be the newest, so if there's one already we don't make any changes to the object map
      if (!dedupedBySubject[newsletter.subject])
        dedupedBySubject[newsletter.subject] = newsletter;
    });

  let nls = [];
  // iterate over the map we have of subject->newsletter, and push into a fresh array, which we'll return
  for (let subject in dedupedBySubject) {
    nls.push(dedupedBySubject[subject]);
  }

  return nls;
};
```

And with that, our journey is complete - we've created a `/newsletter` page that shows a list of all of our newsletters, with a thumbnail image for each one. We've also added a `/newsletter/$id` page that shows the full content of a given newsletter.

## Wrap-up

I hope this post has been helpful to you, and that you've learned something new about how to use ConvertKit's API to create a custom newsletter index page for your Remix site. To see what this looks like in practice, head over to [primaryfocus.tv/newsletter](https://primaryfocus.tv/newsletter).

In my next post, I'll share how I used a similar implementation in **Next.js** on my site - [mikebifulco.com](https://mikebifulco.com).

If you have any questions, or if you've found a bug in my code, please feel free to reach out to me on Twitter [@irreverentmike](https://twitter.com/irreverentmike)!


Publish your newsletter to your Remix site with the ConvertKit API

Improve discoverability by publishing past issues

Using the ConvertKit API to publish newsletters to a Remix site

Keeping your ConvertKit API Secret key safe on Remix sites


## SEO & analytics help grow site traffic

Whether you're working on your own blog, a news site, or building a product, you _absolutely must_ care about your site's SEO. If your site is not optimized for search engines, it is harder to find, leading to fewer visitors and potential customers. SEO tools can help you improve the usability of your site, making it easier for users to find the information they are looking for.

These are the tools that I use to monitor and enhance my sites' performance. The can help you build a site that is easier to find and use, too.

## ahrefs webmaster tools

You only need to spend a few moments researching SEO online before ahrefs pops up _somewhere_ in your results. In addition to their incredible [blog](https://ahrefs.com/blog/) and [studies](https://ahrefs.com/blog/category/data-studies/) on how search works on the web, they provide a fantastic suite of free tools for monitoring and improviing the SEO on your sites.

<Image
  publicId="posts/seo-tools-for-new-projects/ahrefs-audit"
  alt="Screenshot of a weekly audit email from ahrefs - showing a 100 SEO score for mikebifulco.com, with a few warnings."
  caption="There's always room to improve SEO, and ahrefs webmaster tools makes it easy to digest"
/>

I have found [ahrefs webmaster tools](https://ahrefs.com/webmaster-tools) to be absolutely invaluable in keeping an eye on my sites' content. Once you register a free account and verify that you have control of the sites you want to monitor, ahrefs will kick off a weekly audit of all the pages on your domain. It will check for common pitfalls, and give your site a health score from 0-100. If you're a dev, it may be helpful to think of it as a linter for SEO.

I've used it to find and fix countless problems with my sites, from broken links to missing Canonical URLs, removing unnecessary redirects and finding opportunities to link existing articles to one another.

You will get weekly audit reports in email, which let you know when things change - this can be helpful in situations where things out of your control end up affecting your site. Ever had someone take down an article that you link to? Ahrefs will find it.

## Google Search Console

My adoption of [Google Search Console](https://search.google.com/search-console/about) come from what I learned taking Monica Lent's [Blogging for Devs](https://bloggingfordevs.com) course.

Google Search Console gives you reports on how and when people see your site pop up in Google Search results. Note that it won't track people _on your site_ like Google Analytics and Fathom do - just your performance in search. This is a useful litmus for your site's organic growth and authority. If you're investing in sharing your expertise and building a searchable site, your performance on Google Search Console should grow over time. In other words, you can see whether you're gaining traction via SEO or not.

To get started, you'll need to register your site with the Google Search Console. Verifying your ownership takes a few quick steps, and doesn't require you to add Google Analytics (which is helpful if, like me, you've chosen [Fathom](https://mikebifulco.com/posts/why-fathom-analytics) for its privacy-first features).

Best of all, it's free! Just register and follow instructions to add a DNS record, or upload a file to a specific place to verify that you own the site you're interested in monitoring. You should make sure to have a sitemap on your site - they're easy to generate, and worth the time to get right. This is what Google's crawlers primarily use to index your articles for search results.

I use the Search Console to make decisions about things to write about next, and track the progress of my site over time. At the moment, Google will keeps 16 months of your site's traffic history around for you to analyze, but that history starts once you've registered you site with the Search Console. So, the sooner you get set up, the better!

## Fathom Analytics

[Fathom](https://usefathom.com) is privacy first analytics for the web. According to their site, _Fathom is a Google Analytics alternative that doesn’t compromise visitor privacy for data. We revolutionized website analytics by making them easy to use and respectful of privacy laws (like GDPR and more)._

If you've never paid attention analytics for your web properties, Fathom will be a revelation - it's super useful to have an understanding of which pages on your site are getting traffic, where that traffic is coming from, and what times of day are most busy.

If you've used Google Analytics in the past, you may be surprised just how freeing it is to use an analytics tool that prioritizes analytics. You _really_ don't need to know _who_ is on a given page - instead, focusing on the content on your site which is being visited, and the journey readers take to get there is a super useful tool to have when you're researching and writing new articles.

It's great, and puts your readers' privacy first. Google's advantage is quickly vanishing due to new regulations, and privacy tools that are being built into browsers and operating systems. Fathom does a great job of providing value without fishing for every minute detail about your readers.

Fathom is lightweight and ridiculously easy to use. The Fathom team provides docs for a variety of platforms and JAMstack site builders, including [Gatsby](https://usefathom.com/docs/integrations/gatsby), [ConvertKit](https://usefathom.com/docs/integrations/convertkit), [Next.js](https://usefathom.com/docs/integrations/next), [Vue](https://usefathom.com/docs/integrations/vue), [Webflow](https://usefathom.com/docs/integrations/webflow), [Wordpress](https://usefathom.com/docs/integrations/wordpress), and quite a few more.

I've written a bit about my experiences with Fathom before. You may want to check out my other articles, including: [Why I switched to Fathom for Analytics](https://mikebifulco.com/posts/why-fathom-analytics) and [How to add Fathom Analytics to your Remix.run app](https://mikebifulco.com/posts/add-fathom-analytics-to-remix)

### Self-host Fathom for free - Fathom Lite

If you're hesitant to pay for Fathom, they do also provide an open source version called [Fathom Lite](https://github.com/usefathom/fathom) - you'll need to configure and host it yourself, but it should give you an idea of what Fathom's premiums service is like.

If you're interested in trying out Fathom's paid service, use my [**referral link**](https://usefathom.com/ref/DPSSYB) for a discount to get you started.

## Cloudflare

I use [Cloudflare](https://cloudflare.com) to manage the DNS records for all of my sites. In addition to having a _really_ straightforward UI for DNS management, they offer a host of other features to keep your sites running well. This includes automated protection for DDoS attacks, maintenance mode, and performance enhancements such as origin server optimization and caching.

Cloudflare provides a [Free Tier](https://www.cloudflare.com/plans/) that will work for most personal sites. You'll need to set up an account, look for the instructions to add your domain to your Cloudflare account, and then update your DNS settings as needed.

Because I own domains from a variety of registrars, it's really nice to be able to manage DNS for all of them in one place. They also provide a ton of other great dev tools, like [Cloudflare Workers](https://workers.cloudflare.com/), which you can use to add interactivity to your site.

## F5Bot

<Image
  publicId="posts/seo-tools-for-new-projects/f5bot"
  alt="Screenshot of f5bot.com - get an email for when you're mentioned online!"
  caption="F5bot is free, and dead simple to set up. "
/>

The pitch for [f5bot](https://f5bot.com) is simple - as they say, it is a service that will help you to "Get an email when you're mentioned online!".

It's completely free, and takes just moments to set up - you just need to create an account, and set up keywords for the service to track. When your keywords are mentioned on [Reddit](https://reddit.com), [Hackernews](https://news.ycombinator.com), or [Lobste.rs](https://lobste.rs), you'll get a tidy little email in your inbox.

<Image
  publicId="posts/seo-tools-for-new-projects/f5bot-notification "
  alt="screenshot of a notification from f5bot in my gmail inbox. It's a simple plaintext email with a link to an article on mikebifulco.com that was mentioned on Reddit."
  caption="This is what typical notification from f5bot looks like."
/>

Notifications come _very_ quickly - in my experience, I see them within minutes of my sites being mentioned online. This is hugely helpful because it allows you to respond quickly, strike up a conversation, and make a connection with the people who are sharing your work. Those connections are the backbone of building a great personal brand online.

You can set up any search keyword you want, so if there's a competitor or topic that you're hoping to keep an eye on, it's great for that, too.

Overall, I highly recommend [f5bot](https://f5bot.com) - it's an incredibly useful tool, it's free, and it couldn't be easier to set up.

## Related reading

If you're going on the SEO-improvement journey for your sites, you might find these helpful:

- [Why I switched to Fathom for Analytics](https://mikebifulco.com/posts/why-fathom-analytics)
- [How to add Fathom Analytics to your Remix.run app](https://mikebifulco.com/posts/add-fathom-analytics-to-remix)
- [Don't center-align paragraph text](https://mikebifulco.com/posts/dont-center-paragraph-text) - this is utterly unrelated to SEO, but c'mon, do better.
- [SEO for Devs](https://seofordevs.com) - I absolutely cannot recommend this **free course** enough. Monica Lent has a masterful understanding of SEO, and I've learned a ton from her over the years.


SEO tools I used to grow my sites to 20k+ visitors/month


## Semantic HTML makes your sites better

Semantic HTML is important because it helps improve the accessibility of a web page and makes the code more readable. Semantic elements are those that clearly describe their meaning in a way that is easy for both humans and machines to understand.

Search engines can more easily parse and understand semantic HTML, [which can help improve your website's SEO](https://developers.google.com/style/semantic-tagging). Semantic HTML uses tags to describe the meaning of content on a page, rather than just its presentation. This can help search engines better understand the content of a page and index it appropriately.

### Using h2 as a subtitle for an h1 is incorrect

According to the [html spec](https://html.spec.whatwg.org/multipage/dom.html#heading-content-2), `h1` through `h6` tags are meant to indicate the structure of a document. In other words, each page should have at most 1 `<h1>` tag, and `<h2>` elements should be _sub-sections_ of that `h1` - not additional descriptions for it.

This [warning from the HTML spec](https://html.spec.whatwg.org/multipage/dom.html#sectioning-content) does a great job of explaining it:

> For example, the following snippet, intended to represent the heading of a corporate site, is non-conforming because the second line is not intended to be a heading of a subsection, but merely a subheading or subtitle (a subordinate heading for the same section).
>
> ```html
> <body>
>   <h1>ACME Corporation</h1>
>   <h2>The leaders in arbitrary fast delivery since 1920</h2>
>   ...
> </body>
> ```

(07/05/2022) As of the time of this writing, whatwg goes on to recommend use of `hgroup` in its solution. [According to MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hgroup#usage_notes), hgroup should not be used, as it is not supported by assistive technologies needed for accesible reading of HTML sites.

## Use this code to add subtitles to headings

The correct semantic structure of HTML for a heading with a subtitle is straightforward - nest your `<h1>`, etc with in a `<header>` tag, and include a `<p>` tag with an appropriate class name as a sibling to that `h1`:

```html
<header>
  <h1>How to bootstrap a product as a solo founder</h1>
  <p class="tagline">
    Important lessongs learned from building 10 products on my own in 2 years
  </p>
</header>
```

For more details on this, check out [MDN docs on the header tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header), and their [semantics section](https://developer.mozilla.org/en-US/docs/Glossary/Semantics).

### 🚨 UPDATE: I was wrong! 🚨

The first version of this article was wrong! I previously recommended using the `<hgroup>` tag as per the whatwg spec, but I was corrected by [@AnalyticsEqv](https://twitter.com/AnalyticsEqv) on twitter:

<blockquote class="twitter-tweet">
  <p lang="en" dir="ltr">
    MDN specifically recommends against &lt;hgroup&gt; because assistive
    technologies don&#39;t support it.
  </p>
  &mdash; EQV Analytics 🇺🇦 (@AnalyticsEqv) <a href="https://twitter.com/AnalyticsEqv/status/1544328749272993792?ref_src=twsrc%5Etfw">July 5, 2022</a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8" />

Thanks for the correction! I definitely get things wrong sometimes, and I'm always happy to correct myself when appropriate.

## Did you find this helpful?

You might also like these other articles I've written:

- [How to run dependabot locally on your projects](https://mikebifulco.com/posts/run-dependabot-locally)
- [No Floating Promises: an eslint rule to prevent async code errors](https://mikebifulco.com/posts/eslint-no-floating-promises)
- [JavaScript tips: nullish coalescing](https://mikebifulco.com/posts/nullish-coalescing-javascript)

If you want to hear more from me, consider subscribing to my newsletter 👇🏼


The correct semantic HTML for adding subtitles to h1 tags

Using h2 as a subtitle for an h1 is incorrect

Use this code to add subtitles to headings


Building a website using the Remix.run web app framework? This tutorial will teach you how to add privacy-first analytics to your Remix site with Fathom.

## How to set up Fathom on your Remix site

1. Sign into your account with [Fathom](https://usefathom.com/login), and create a new site.
2. Open the settings for that site, and look for _Script settings_. Hit the clipboard icon to copy the Script tag for your site.

   <Image
     publicId="posts/add-fathom-analytics-to-remix/script-settings"
     alt="Script settings for one of my sites on Fathom's dashboard"
     caption="You site's embed code will be on the script settings page. Hit the clipboard button to copy the code"
   />

3. Open up your Remix site in your IDE of choice. open `root.tsx` (or `root.jsx` if you're using JavaScript instead of TypeScript), and paste your embed code right before the `<Script />` tag:

```jsx
return (
  <html lang="en">
    <head>
      <Meta />
      <Links />
    </head>
    <body>
      <Layout>
        <Outlet />
      </Layout>
      <ScrollRestoration />

      <script
        src="https://cdn.usefathom.com/script.js"
        data-site="TRSSCIOR"
        defer
      />
      <Scripts />
      <LiveReload />
    </body>
  </html>
);
```

<small>
  
  _Note: ☝🏽 I've edited the `<script>` tag here to be self closing, rather than having `<script></script>`. It should work either way._

</small>

4. Start your site with `npm run dev` or `yarn dev` and visit any page (you may have to hit reload if you had the page open already). You should see this reflected in your fathom dashboard in real time!
   <Image
     publicId="posts/add-fathom-analytics-to-remix/tracking-results"
     alt="You'll know it's working when you see a live visitor on your fathom dashboard"
     caption="You'll know it's working when you see a live visitor on your fathom dashboard"
   />

## Try out Fathom - it's great!

I've been using Fathom for years, and am a happy paying customer. If you'd like to give it a shot, you can get $10 off of Fathom when you **use my referral link [https://usefathom.com/ref/DPSSYB](https://usefathom.com/ref/DPSSYB)** to get started.

## If you enjoyed this video

- I wrote a post when I initially adopted fathom, called [Why I switched to Fathom for analytics](https://mikebifulco.com/posts/why-fathom-analytics)
- Make sure to [subscribe to my YouTube channel](https://www.youtube.com/channel/mikebifulco)


#tutorial: 6 posts tagged