Writing ·

Tell the web where you are

You spend hours on the writing. You spend zero seconds on the four lines of HTML that tell the rest of the web what your site is, who wrote it, and where you are.

Then you submit to a directory and we cannot list you. The reviewer cannot find a description. The reviewer cannot find a city. The reviewer moves on. Your beautiful blog becomes another tab they close.

This is fixable. It takes about ten minutes. Once. Forever.

The bare minimum

Open the source of your homepage. Look in the <head>. You need three tags, no exceptions.

<title>Your Name — A blog about whatever</title>
<meta name="description" content="One sentence about what you write here. Keep it under 160 characters." />
<link rel="canonical" href="https://yourdomain.com/" />

The title is what shows up in browser tabs and search results. The description is what shows up underneath in search results, and what every directory on earth pulls when it lists you. The canonical URL stops the same page from being indexed under three different URLs at once.

Most personal blogs ship the title. Most personal blogs forget the description. The description is what tells a stranger whether to click. Write it.

The social card

When someone pastes your URL into Mastodon, Slack, iMessage, or anywhere with a link preview, these are the tags that decide what shows up.

<meta property="og:type" content="website" />
<meta property="og:title" content="Your Name — A blog" />
<meta property="og:description" content="The same one sentence." />
<meta property="og:url" content="https://yourdomain.com/" />
<meta property="og:image" content="https://yourdomain.com/og.png" />
<meta name="twitter:card" content="summary_large_image" />

The image is a 1200×630 PNG with your name and one line on it. Make one in any tool. Put it at /og.png. Done.

Without these, your link is a sad grey rectangle with your domain name in 9pt type. With them, it looks like a thing somebody made on purpose.

JSON-LD: the part nobody tells you about

Search engines, AI crawlers, and serious directories don't read your prose to figure out what your site is. They read structured data. The format is JSON-LD, and it lives in a <script> tag in your <head>.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Your Name's Blog",
  "url": "https://yourdomain.com/",
  "author": {
    "@type": "Person",
    "name": "Your Name",
    "url": "https://yourdomain.com/about"
  },
  "inLanguage": "en"
}
</script>

That's it. Five fields. Schema.org has hundreds of types and thousands of properties; you do not need any of them. WebSite + Person author is enough to let a parser know you exist as a named human running a named site.

Where you are

This is the bit most people skip and the bit most directories need.

Add a location to the author. The schema is homeLocation with a Place nested inside, with a PostalAddress nested inside that. It looks like overkill. It is the standard.

"author": {
  "@type": "Person",
  "name": "Your Name",
  "url": "https://yourdomain.com/about",
  "homeLocation": {
    "@type": "Place",
    "address": {
      "@type": "PostalAddress",
      "addressLocality": "Lisbon",
      "addressRegion": "Lisbon District",
      "addressCountry": "PT"
    }
  }
}

Three fields matter: addressLocality (your city), addressRegion (your state, province, or region — required if you live somewhere that has them), and addressCountry (the ISO 3166-1 alpha-2 code, two letters, uppercase: US, CA, GB, DE, JP).

That's the whole thing. A directory parser can now place your blog on a map without guessing, without asking, without giving up and skipping you.

The h-card alternative

If you're already in the IndieWeb world, you can express the same data with microformats2 and an h-card. Either works. Most directories parse both. Pick one. Don't ship both with conflicting data.

<p class="h-card">
  <a class="p-name u-url" href="https://yourdomain.com/">Your Name</a>,
  <span class="p-locality">Lisbon</span>,
  <span class="p-country-name">Portugal</span>
</p>

Test it before you ship it

Two free tools:

validator.schema.org parses your JSON-LD and tells you which fields are missing or malformed. Paste your URL. Read the warnings. Fix them.

Google's Rich Results Test shows you what Google specifically extracts. If it doesn't see your author or your location, neither does any other crawler downstream of Google.

Why this matters here

Every blog on this directory is filed by city. We render a page for every city, every state, every country. Your blog only exists on those pages if we know where you are.

We do not guess. We do not infer "probably in Brooklyn" from your byline. We read the meta and the JSON-LD. If they're missing, we close the tab.

So write the description. Write the JSON-LD. Add your city. Then submit. The reviewer's job becomes a five-second yes instead of a hunt that ends in no.