Skip to content

Domain Playbook

The goal is simple: publish the personal site for zero hosting cost, avoid DNS drama, and keep the path open for paid skill access later.

Current Answer

Vercel can host the personal MkDocs site on Hobby and can attach custom domains on Hobby.

Vercel Hobby is not the right long-term default if the same site will request payment, advertise a paid service, or process Stripe subscriptions. Vercel's fair-use rules restrict Hobby teams to non-commercial personal use, and they explicitly count requesting or processing payment from visitors as commercial usage.

That makes Vercel fine for the public/personal phase and wrong for the paid-access phase unless the project moves to Pro.

Zero-Money Domain Reality

There are two different things people call a custom domain:

  • an owned apex/root domain such as firstlast.com
  • a free hosted or community subdomain such as project.vercel.app, project.pages.dev, project.netlify.app, username.github.io, or name.is-a.dev

The first one normally costs money because a registrar has to register and renew it. Free hosting does not make domain registration free.

The second one can cost zero, but it means using somebody else's root domain. That is acceptable for a first launch, less durable for a serious public identity, and weaker for email, long-term reputation, and portability.

Recommendation

Use Netlify or Cloudflare Pages as the default free host if future Stripe payments are a serious requirement.

Use Vercel only if the first release is purely personal and non-commercial.

For this MkDocs site, the stack should stay boring:

  • Markdown source in docs/
  • MkDocs config in mkdocs.yml
  • generated static files in site/
  • build command: pip install -r requirements-docs.txt && mkdocs build
  • publish directory: site
  • host-provided domain first, owned domain later

Domain Name Rules

Pick the domain that is easiest to say out loud.

Good patterns:

  • firstlast.com
  • firstlast.co
  • firstnamelastname.com
  • firstlast.dev
  • lifeengine.dev if the project brand matters more than the person name

Avoid:

  • hyphens
  • clever spellings
  • hard-to-pronounce endings
  • domains that trap the site inside a project name you may outgrow

Free Launch Paths

Netlify

Best fit if future commercial use matters and you want to keep hosting at zero while traffic is small.

The repository now includes netlify.toml:

[build]
  command = "pip install -r requirements-docs.txt && mkdocs build"
  publish = "site"

Netlify gives a free *.netlify.app domain and supports custom domains with SSL on the free plan.

Cloudflare Pages

Best fit if DNS, static hosting, and later Cloudflare-native access control might matter.

Use these project settings:

  • build command: pip install -r requirements-docs.txt && mkdocs build
  • build output directory: site
  • production branch: main or whatever repository branch becomes canonical

Cloudflare Pages gives a free *.pages.dev domain and supports custom domains on the free plan.

Vercel

Best fit if the first public version is personal, non-commercial, and dashboard smoothness matters more than the later Stripe constraint.

The repository now includes vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "pip install -r requirements-docs.txt",
  "buildCommand": "mkdocs build",
  "outputDirectory": "site"
}

Vercel gives a free *.vercel.app domain and allows custom domains on Hobby, but the paid skill-access version should not stay on Hobby.

GitHub Pages DNS Shape

If hosting on GitHub Pages, use this pattern:

  • apex domain: A records pointing at GitHub Pages
  • www: CNAME pointing at <username>.github.io
  • repository setting: add the custom domain under Pages
  • commit a CNAME file only if publishing from a branch source

GitHub Pages is useful for personal/project sites, but it is not a clean default for a paid SaaS-like access model.

Vercel DNS Shape

If hosting on Vercel, add the domain under the project settings.

Vercel will show the exact records for that project:

  • apex domain: usually an A record
  • subdomain: usually a CNAME record
  • wildcard domains: use nameserver verification

Stripe Shape

Stripe solves payment collection. It does not by itself solve access control.

For a paid skill library, the missing pieces are:

  • identity: who is this subscriber?
  • entitlement: what has this subscriber paid for?
  • delivery: where do they access the skill files?
  • revocation: what happens after cancellation or failed payment?

The first commercial version should probably be manual:

  1. Public MkDocs site explains the offer.
  2. Stripe Payment Link collects the subscription.
  3. Access is granted manually to a private repo, private folder, email list, or customer-only download.
  4. Stripe Customer Portal handles subscription management.

The automated version is a separate application concern. Keep MkDocs as the public trust and documentation surface; add a small authenticated app only when manual fulfillment becomes painful.

Versioning

Use normal Git history for the public website at first.

Use mike only if the site begins publishing versioned documentation or paid skill releases where older versions must remain addressable. Versioning adds moving parts; it should be introduced when there is a real release line, not just because the tool exists.

References