Custom Structures

Suggested Repository Structure

Create a dedicated repository for your custom structures organized by category:

structures/
├── category1/
│   ├── structure1.yaml
│   └── structure2.yaml
├── category2/
│   ├── structure1.yaml
│   └── structure2.yaml

Referencing Custom Structures

folders:
  - ./:
    struct:
      - category1/structure1
      - category2/structure2
    with:
      var_in_structure1: 'value'

Using the Structures Path

Point StructKit to your custom structures using the -s option:

structkit generate -s ~/path/to/custom-structures/structures file://.structkit.yaml ./output

Or set the STRUCTKIT_STRUCTURES_PATH environment variable for a persistent default.

Named Custom sources (structkit sources)

Keywords: sources, structkit sources, STRUCTKIT_SOURCES_CONFIG, STRUCTKIT_SOURCES_CACHE, named sources, git-backed sources.

StructKit can store named structure sources in a user-level config file. This is useful when you reuse a shared template directory or GitHub repository and do not want to pass --structures-path or set STRUCTKIT_STRUCTURES_PATH every time.

structkit sources add company ./templates
structkit sources add platform httpdss/platform-structures
structkit sources add versioned github://httpdss/platform-structures@v1/structures
structkit sources list
structkit sources show company
structkit sources validate company
structkit sources remove company

STRUCTKIT_SOURCES_CONFIG — sources config file

By default, sources are written to $XDG_CONFIG_HOME/structkit/sources.yaml or ~/.config/structkit/sources.yaml. Set STRUCTKIT_SOURCES_CONFIG to use a different file, or pass structkit sources --config-path <file>.

Named sources support:

• Local filesystem directories, such as ./templates or ~/platform/structures
• GitHub shorthand, such as httpdss/platform-structures
• GitHub URLs, such as github://httpdss/platform-structures or github://httpdss/platform-structures@v1/structures
• Query-style refs for branch names that contain slashes, such as github://httpdss/platform-structures/structures?ref=release/1.x
• Git URLs, including HTTPS, SSH, and file:// repositories

STRUCTKIT_SOURCES_CACHE — git-backed sources cache

Git-backed sources are cloned into $XDG_CACHE_HOME/structkit/sources or ~/.cache/structkit/sources by default. Set STRUCTKIT_SOURCES_CACHE to use a different cache directory. StructKit runs git fetch when a git-backed source is resolved or validated. Branch refs are checked out from origin/<branch>; tag and commit refs are checked out detached so tags and SHAs do not run git pull.

File-Local sources: in .structkit.yaml

A committed .structkit.yaml can declare its own named sources under a top-level sources: key. This keeps generation portable and protects the file from changes to a user's global structkit sources configuration.

sources:
  platform:
    url: github://httpdss/platform-structures@v1.2.0/structures

folders:
  - ./:
      struct: platform/python/service
      with:
        service_name: demo-api

File-local sources override user-level sources with the same name at the top level. Nested structs inherit the parent's source context, and a nested struct cannot silently redefine an inherited source name to a different URL/path. Use a different source name when you intentionally need two versions:

sources:
  platform_v1:
    url: github://httpdss/platform-structures@v1/structures
  platform_v2:
    url: github://httpdss/platform-structures@v2/structures

folders:
  - ./:
      struct:
        - platform_v1/python/service
        - platform_v2/github/actions-ci

Unqualified nested structs inherit the current structures path. If platform/python/service references github/actions-ci, that child struct resolves from the same pinned platform source unless it uses another named source or a fully qualified remote reference.

You can also reference a remote struct directly:

folders:
  - ./:
      struct: github://httpdss/platform-structures@v1.2.0/structures/python/service

For reproducible .structkit.yaml files, prefer tags or commit SHAs over mutable branches.

Example: Versioned Sources

The examples/versioned-sources/ directory in the StructKit repo demonstrates file-local sources and nested-struct source inheritance with a local source so it runs offline.

structkit generate examples/versioned-sources/.structkit.yaml /tmp/structkit-versioned-sources-demo

# Preview without writing files
structkit generate examples/versioned-sources/.structkit.yaml /tmp/structkit-versioned-sources-demo --dry-run --diff

Use a source explicitly with --source:

structkit list --source company
structkit generate --source company project/python ./app

# Or with the inline "source/structure" form:
structkit generate company/project/python ./app