reid/jigyll
1
0
Code Issues 1 Projects Packages Wiki Activity Actions

Install themes from pinned archives without git clone #1

New issue
Open
opened 2026-11-03 21:22:44 -05:00 by reid · 0 comments
reid commented 2026-11-03 21:22:44 -05:00
Owner
Copy link

Install themes from pinned archives without git clone

Problem

jigyll new --theme accepts a Git repository URL and installs a checkout. Theme consumers should be able to install an immutable source archive without cloning repository history or keeping a .git directory.

Docifly is a concrete use case: it ships compiled CSS and browser scripts, so a source archive contains everything a consumer needs to build documentation.

Existing capability

The current Jigyll source already supports remote_theme: owner/repository@<40-character-SHA> for GitHub source archives, including download, safe extraction and caching (site/remote_theme*.go). This issue concerns the new --theme installation workflow and explicit archive URLs, including Forgejo-hosted archives; do not duplicate the existing resolver or imply all archive-theme support is missing.

Requested behavior

Allow the theme installer to accept a versioned release archive or commit-pinned archive URL, download it, and install ordinary theme files under _theme/<name>/ without invoking git clone.

Illustrative interface (final naming to follow existing CLI conventions):

jigyll new my-docs --theme https://forge.example/owner/docifly/archive/<full-commit-sha>.tar.gz
  • Support at least .tar.gz; document supported archive formats and URL requirements.
  • Handle the single enclosing directory used by GitHub/Forgejo source archives.
  • Resolve the installed theme name explicitly and set the consumer's theme configuration correctly; never derive the theme name from a commit SHA.
  • Provide checksum verification and record the source URL and expected/observed digest so consumers can reproduce a pinned installation.
  • Reuse existing archive download/extraction safeguards where appropriate: reject traversal, unsafe links and unreasonable compressed/extracted sizes or entry counts.
  • Validate the archive before publishing the installed directory; failed HTTP requests, integrity checks or extraction must not leave a partially created site/theme or overwrite an existing target.
  • Retain existing Git URL installation behavior. No feature flag, sandbox mode, extra frontend dependency or new runtime controller.

Acceptance criteria

  • A real packaged documentation theme installs from a pinned archive and builds with its shipped layouts/includes/assets, without repository history or a git clone subprocess.
  • Archive installation works when Git is absent from PATH; ordinary builds need no Git, Node, npm or Sass to consume precompiled theme assets.
  • Both archive wrapper normalization and theme-name/configuration handling are covered.
  • Local-only functional verification uses a local HTTP server and a real theme archive, not a live public service or mocked installer.
  • Unit/boundary tests cover valid archives, failed downloads/checksums, malicious archive paths/links, size limits and unchanged destinations after failure.
  • Installer documentation distinguishes Git URL installation, archive installation and the existing pinned GitHub remote_theme workflow, with reproducible examples.

Scope

Archive-based theme installation only. Automatic updates, branch/tag resolution, dependency managers and release automation are not required.

# Install themes from pinned archives without git clone ## Problem `jigyll new --theme` accepts a Git repository URL and installs a checkout. Theme consumers should be able to install an immutable source archive without cloning repository history or keeping a `.git` directory. Docifly is a concrete use case: it ships compiled CSS and browser scripts, so a source archive contains everything a consumer needs to build documentation. ## Existing capability The current Jigyll source already supports `remote_theme: owner/repository@<40-character-SHA>` for GitHub source archives, including download, safe extraction and caching (`site/remote_theme*.go`). This issue concerns the `new --theme` installation workflow and explicit archive URLs, including Forgejo-hosted archives; do not duplicate the existing resolver or imply all archive-theme support is missing. ## Requested behavior Allow the theme installer to accept a versioned release archive or commit-pinned archive URL, download it, and install ordinary theme files under `_theme/<name>/` without invoking `git clone`. Illustrative interface (final naming to follow existing CLI conventions): ```sh jigyll new my-docs --theme https://forge.example/owner/docifly/archive/<full-commit-sha>.tar.gz ``` - Support at least `.tar.gz`; document supported archive formats and URL requirements. - Handle the single enclosing directory used by GitHub/Forgejo source archives. - Resolve the installed theme name explicitly and set the consumer's `theme` configuration correctly; never derive the theme name from a commit SHA. - Provide checksum verification and record the source URL and expected/observed digest so consumers can reproduce a pinned installation. - Reuse existing archive download/extraction safeguards where appropriate: reject traversal, unsafe links and unreasonable compressed/extracted sizes or entry counts. - Validate the archive before publishing the installed directory; failed HTTP requests, integrity checks or extraction must not leave a partially created site/theme or overwrite an existing target. - Retain existing Git URL installation behavior. No feature flag, sandbox mode, extra frontend dependency or new runtime controller. ## Acceptance criteria - A real packaged documentation theme installs from a pinned archive and builds with its shipped layouts/includes/assets, without repository history or a `git clone` subprocess. - Archive installation works when Git is absent from PATH; ordinary builds need no Git, Node, npm or Sass to consume precompiled theme assets. - Both archive wrapper normalization and theme-name/configuration handling are covered. - Local-only functional verification uses a local HTTP server and a real theme archive, not a live public service or mocked installer. - Unit/boundary tests cover valid archives, failed downloads/checksums, malicious archive paths/links, size limits and unchanged destinations after failure. - Installer documentation distinguishes Git URL installation, archive installation and the existing pinned GitHub `remote_theme` workflow, with reproducible examples. ## Scope Archive-based theme installation only. Automatic updates, branch/tag resolution, dependency managers and release automation are not required.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
No results found.
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
reid/jigyll#1
No description provided.