How to Get Started Publishing a Static Site with sourcehut pages

Updated

sourcehut pages publishes static websites for sourcehut users. Every sourcehut user gets a username.srht.site domain, and you can also bring your own domain. It works with any content generator — Jekyll, Hugo, Doxygen, or your own — and provides automatic, zero-config TLS. The site's own quick start claims you can get published in 3 minutes.

What you need before you start

  • A sourcehut account (the username.srht.site domain is tied to your sourcehut username).
  • A directory of static output: HTML, CSS, JS, images. If you use a generator, run its build step first so you have the final files, not the source templates.
  • A way to run sourcehut's command-line tooling or push to a sourcehut git repository, depending on which deployment path you choose.

The quick start path

sourcehut pages documents a "Quick start" flow that gets a site live in about three minutes. The general shape is:

  1. Build your site locally so the output directory contains only static files.
  2. Publish that directory to sourcehut pages using the documented quick start method.
  3. Visit username.srht.site to confirm the site is live.

The exact commands and any required configuration belong to the current sourcehut pages documentation — check the Quick start page there before running anything, since the tooling and flags are the part most likely to have changed.

Deploying your content

sourcehut pages supports more than one deployment route, and the documentation splits them into separate guides:

  • Quick start — the fastest path for a first site.
  • Automating deployments — for rebuilding and republishing on every change, typically wired into sourcehut's CI.
  • Custom domains — for serving the site from your own domain instead of username.srht.site.
  • Managing Permissions — for controlling who can publish or modify the site.
  • Advanced settings — for configuration beyond the defaults.

If you only want one site online today, start with Quick start. Move to Automating deployments once manual republishing becomes annoying.

Domains and TLS

Two things are handled for you:

  • Domain: you get username.srht.site immediately, and you can bring your own domain (BYOD) if you prefer.
  • TLS: described as automatic and zero-config, so you don't manage certificates yourself.

If you use a custom domain, expect to configure DNS at your registrar to point at sourcehut pages; the Custom domains guide covers the specific records.

Common sticking points

  • Publishing source instead of output. If your generator writes to _site, public, or dist, publish that directory — not the project root.
  • Assuming a specific menu or button. The deployment interface is documented per method; follow the Quick start or Automating deployments page rather than guessing at UI locations.
  • Skipping the limitations page. sourcehut pages has a documented Limitations section. Read it before you commit to the platform for a site with unusual requirements.
  • Forgetting permissions. If a collaborator needs to publish, that's the Managing Permissions guide, not the quick start.

Where to go next

The sourcehut pages site links out to: Quick start, Custom domains, Automating deployments, Managing Permissions, Advanced settings, Limitations, REST API, GraphQL API, Gemini support, Additional features, and an FAQ. For a first site, Quick start plus Custom domains covers most of what you need; the API pages matter only if you're integrating publishing into your own tooling.