Skip to content
internal/urls
Updated
On this page

Building absolute URLs from relative paths, so a locale-prefixed or version-pinned address is derived rather than assembled from a hardcoded base URL.

#internal/urls

#internal/urls

Package urls builds absolute URLs from relative paths, decoupling URL generation from a hardcoded base_url and supporting locale-prefixed and versioned paths.

Project identification uses two identifiers, and they are not interchangeable:

- slug: the machine identifier (URL-safe, lowercase, hyphens) used in URLs, directory names, cross-references, frontmatter and manifest keys. - name: the human-readable display name (which may carry spaces, capitals and special characters) used in UI, homepages and documentation.

#URLBuilder

Go go
type URLBuilder interface

URLBuilder builds absolute URLs from relative paths.

Two implementations exist: [SimpleURLBuilder] for a project that is its own site, and [TopologyURLBuilder] for one a shared site mounts under a slug.

#SimpleURLBuilder

Go go
type SimpleURLBuilder struct

SimpleURLBuilder joins a base URL with paths.

It strips trailing slashes from the base URL and handles path joining, so base plus "/" plus path never produces a double slash.

#TopologyURLBuilder

Go go
type TopologyURLBuilder struct

TopologyURLBuilder builds URLs for a topology-aware multi-project deployment, incorporating the project slug under a shared docs base.

With a docs base of "https://docs.smmh.dev" and a slug of "selfdoc", PageURL("guide/") returns "https://docs.smmh.dev/selfdoc/guide/".

Site-level pages are the exception, and the reason this type rather than its callers decides: a post is a citizen of the site, not of the project that wrote it. The site serves every project's posts from one shared "blog/" at the site root, so PageURL("blog/hello/") returns "https://docs.smmh.dev/blog/hello/" with no slug segment. Assets keep the slug -- a post's OG card, stylesheet and search index are the project's own files and stay in the project's subtree.

#NewSimpleURLBuilder

Go go
func NewSimpleURLBuilder(baseURL string) *SimpleURLBuilder

NewSimpleURLBuilder returns a builder for a project served at baseURL, whose trailing slashes are stripped once, here.

#NewTopologyURLBuilder

Go go
func NewTopologyURLBuilder(docsBase, slug string) *TopologyURLBuilder

NewTopologyURLBuilder returns a builder for a project the site at docsBase serves under slug.

#SimpleURLBuilder.PageURL

Go go
func (b *SimpleURLBuilder) PageURL(path string) string

PageURL returns the absolute URL for a page path.

#SimpleURLBuilder.AssetURL

Go go
func (b *SimpleURLBuilder) AssetURL(path string) string

AssetURL returns the absolute URL for an asset path.

#SimpleURLBuilder.FeedURL

Go go
func (b *SimpleURLBuilder) FeedURL() string

FeedURL returns the absolute URL for the Atom feed.

#SimpleURLBuilder.Base

Go go
func (b *SimpleURLBuilder) Base() string

Base returns the base URL string, with no trailing slash.

#SimpleURLBuilder.Mounted

Go go
func (b *SimpleURLBuilder) Mounted() bool

Mounted reports false: a standalone project's output root is what is served.

#SimpleURLBuilder.MountPrefix

Go go
func (b *SimpleURLBuilder) MountPrefix() string

MountPrefix returns "": with no mount, the project's output root already is the site root.

#SimpleURLBuilder.SiteRoot

Go go
func (b *SimpleURLBuilder) SiteRoot() string

SiteRoot returns the served root, which for a standalone project is its own base.

#TopologyURLBuilder.PageURL

Go go
func (b *TopologyURLBuilder) PageURL(path string) string

PageURL returns the absolute URL for a page path, under this project's slug unless the path is site-level -- see the type's own documentation.

#TopologyURLBuilder.AssetURL

Go go
func (b *TopologyURLBuilder) AssetURL(path string) string

AssetURL returns the absolute URL for an asset path under this project's slug.

#TopologyURLBuilder.FeedURL

Go go
func (b *TopologyURLBuilder) FeedURL() string

FeedURL returns the absolute URL for the Atom feed.

#TopologyURLBuilder.Base

Go go
func (b *TopologyURLBuilder) Base() string

Base returns the base URL string -- the docs base plus the slug, with no trailing slash.

#TopologyURLBuilder.Mounted

Go go
func (b *TopologyURLBuilder) Mounted() bool

Mounted reports true: the site serves a topology project under its slug.

#TopologyURLBuilder.MountPrefix

Go go
func (b *TopologyURLBuilder) MountPrefix() string

MountPrefix returns the slug segment the site serves this project's output under.

#TopologyURLBuilder.SiteRoot

Go go
func (b *TopologyURLBuilder) SiteRoot() string

SiteRoot returns the shared site's root, above this project's slug.

#TopologyURLBuilder.CrossProjectURL

Go go
func (b *TopologyURLBuilder) CrossProjectURL(projectSlug, path string) string

CrossProjectURL builds a URL to another project's content: the docs base, the project's slug, and the path.

Every project the site serves is mounted under its own slug, so the slug is the whole address and there is nothing to declare per project. A slug the site does not serve is not an address this function can tell apart from one it does -- the assembly's verification is what refuses a link naming a project the roster does not carry.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search