sitetemplate

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package sitetemplate resolves and fetches the site templates behind `sarde new site --template`. Official templates live in the getsarde/sarde-templates repository, one folder per template; any public GitHub repository folder works through the owner/repo[/path][#ref] form. Templates are downloaded as GitHub archives, so git is not required.

Index

Constants

This section is empty.

Variables

View Source
var Registry = []Entry{
	{Name: "course", Owner: "getsarde", Repo: "sarde-templates", Subpath: "course"},
}

Registry lists the official templates. Adding one is a row here plus a folder in getsarde/sarde-templates.

Functions

func HideRootFiles

func HideRootFiles(fsys fs.FS, names ...string) fs.FS

HideRootFiles returns fsys without the named root-level entries. The CLI uses it to keep a template's README.md and LICENSE, which describe the template on GitHub, out of the new site.

func Names

func Names() []string

Names returns the official template names, sorted, for help text and error messages.

Types

type Entry

type Entry struct {
	Name    string
	Owner   string
	Repo    string
	Subpath string
}

Entry is an official template: a name users type, and the repository folder it maps to.

type Fetcher

type Fetcher struct {
	// CacheDir holds one archive per owner/repo/ref. Empty disables caching.
	CacheDir string
	// Version is the engine version refs are pinned to.
	Version string
	// Download fetches a URL into a temporary file (the caller removes it).
	Download func(ctx context.Context, url string) (string, error)
}

Fetcher downloads template archives. The zero value is not usable; call DefaultFetcher, or fill the fields in tests.

func DefaultFetcher

func DefaultFetcher() *Fetcher

DefaultFetcher caches under ~/.sarde/templates and downloads from GitHub.

func (*Fetcher) Fetch

func (f *Fetcher) Fetch(ctx context.Context, spec Spec) (*Result, error)

Fetch resolves the ref for spec, obtains the archive (cache or network), and returns the template folder as an fs.FS.

type Resolved

type Resolved struct {
	Ref  string
	Kind download.RefKind
	// Pinned marks an engine-derived tag: its cache entry is authoritative,
	// and a missing tag falls back to main.
	Pinned bool
}

Resolved is the Git ref a fetch will ask GitHub for.

func ResolveRef

func ResolveRef(spec Spec, engineVersion string) Resolved

ResolveRef picks the ref for spec. An explicit "#ref" wins. Third-party templates default to main. Official templates follow the engine: release builds use the tag "v<major>.<minor>" of the templates repository, so a template never relies on engine features the installed version lacks; dev builds use main.

type Result

type Result struct {
	// FS is the template folder: the repository subpath applied, and
	// README.md and LICENSE at its root hidden.
	FS fs.FS
	// Ref is the ref actually used, "main" after a tag fallback.
	Ref string
	// Notices are things the user should know: a missing tag, a cached copy
	// used offline. The caller prints them.
	Notices []string
	// Cleanup closes the archive. Call it once the files are copied.
	Cleanup func()
}

Result is a fetched template, served straight from its zip archive.

type Spec

type Spec struct {
	Input    string // as typed, for messages
	Owner    string
	Repo     string
	Subpath  string // slash-separated folder inside the repository; "" is the root
	Ref      string // explicit ref from "#ref" or a /tree/<branch> URL; "" lets ResolveRef decide
	Official bool   // from the Registry: pinned to the engine's minor version
}

Spec is a parsed --template value.

func Parse

func Parse(input string) (Spec, error)

Parse accepts a registry name ("course"), "owner/repo[/path]", or a github.com URL (with an optional /tree/<branch>/<path>), each optionally followed by "#ref". The ref is cut off first because it may contain "/".

func (Spec) CloneURL

func (s Spec) CloneURL() string

CloneURL is the repository's HTTPS clone URL, offered when a download fails.

func (Spec) Display

func (s Spec) Display() string

Display is the short form used in messages: the registry name, or owner/repo[/path], plus "#ref" when one was given.

type UnknownTemplateError

type UnknownTemplateError struct {
	Name string
}

UnknownTemplateError is returned for a bare name that is not in the Registry. It is decided offline.

func (*UnknownTemplateError) Error

func (e *UnknownTemplateError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL