[v3] Make pretty URLs the default and remove the --pretty-urls CLI flag

[emmadesilva]

Summary

In v3, pretty URLs should be the default output format, and the --pretty-urls build flag should be removed. Build behavior should be config-only. Non-pretty .html URLs remain supported as an explicit opt-out.

---

Motivation

This is a product positioning decision as much as a technical one. Defaults communicate intent. Shipping v3 with .html URLs as the default makes Hyde feel more like a file converter than a static site generator.

Pretty URLs are:

• cleaner for end users (/about vs /about.html)
• the standard expectation in modern SSG ecosystems (Jekyll, Eleventy, Hugo all treat them as normal)
• a better fit for Hyde's own content-first mental model — the routing layer already treats routes as extensionless identifiers

The current --pretty-urls flag correctly exists as opt-in in v2, but inverting that in v3 is the right call.

---

Decision

1. Default pretty_urls to true in the v3 config skeleton
2. Remove the --pretty-urls CLI build flag — config is the single source of truth for build output shape
3. Keep pretty_urls: false in config as the supported opt-out for users who need exact .html output (legacy hosting, migration compatibility, direct file browsing)

---

Why remove the CLI flag entirely rather than invert it

The flag was always conceptually redundant — if config already controls this, the flag is just a second, potentially conflicting source of truth. Removing it:

• simplifies the mental model (build behavior comes from config, full stop)
• removes a maintenance surface that can drift out of sync with docs and tests
• makes the question "what URL shape will my build produce?" answerable in one place

The only reason to keep a flag would be if there were a strong, common one-off workflow requiring a config override at build time. There isn't one that outweighs the cost of maintaining it. Users who need non-pretty output for a one-off should just set it in config.

---

Upgrade / migration notes

This is a breaking default change. The v3 upgrade guide should call it out explicitly:

• Existing projects using pretty URLs: no action needed
• Existing projects relying on .html output: add pretty_urls: false to config
• Projects using --pretty-urls in build scripts or CI: remove the flag (it no longer exists; behavior is now the default)

---

Non-goals

This issue is not about removing ugly URL support — that stays. It's about which mode is normal and which mode is opt-out.