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, projects map[string]string) *TopologyURLBuilder

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

projects maps another project's slug to its base URL, for [TopologyURLBuilder.CrossProjectURL]; it may be nil.

#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, reading the base from the projects mapping the builder was constructed with and falling back to the docs base plus the project slug when the mapping does not name it.

Search