diff --git a/.github/actionlint.yml b/.github/actionlint.yml new file mode 100644 index 0000000..e4b77a0 --- /dev/null +++ b/.github/actionlint.yml @@ -0,0 +1,6 @@ +--- +paths: + # GitHub exposes both fields. Remove this when actionlint's schema includes them. + .github/workflows/jekyll-{build,preview-comment}.yml: + ignore: + - 'property "workflow_(repository|sha)" is not defined' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..ecddcd5 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,110 @@ +--- +name: Theme CI +permissions: {} + +on: + pull_request: + push: + branches: + - master + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + site: + name: Build the example site + uses: ./.github/workflows/jekyll-build.yml + permissions: + contents: read + with: + source_dir: example + config_files: example/_config.yml + + verify-preview: + name: Verify the rendered preview + if: github.event_name == 'pull_request' + needs: site + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout validation script + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ github.event.pull_request.head.sha }} + persist-credentials: false + + - name: Download the same files offered to reviewers + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: ${{ needs.site.outputs.preview_artifact }} + path: ${{ runner.temp }}/preview + + - name: Verify the published paths + run: | + ruby script/verify-preview.rb "$RUNNER_TEMP/preview" '' \ + https://app.lizardbyte.dev/ https://example.org + + - name: Test the Docker preview + run: | + container=$(docker run --rm -d -p 127.0.0.1:8080:80 \ + --mount "type=bind,source=$RUNNER_TEMP/preview,target=/usr/share/nginx/html,readonly" nginx:alpine) + trap 'docker stop "$container" >/dev/null' EXIT + curl --retry 5 --retry-all-errors -fsS http://127.0.0.1:8080/ -o "$RUNNER_TEMP/preview-index.html" + grep -F 'href="#projects"' "$RUNNER_TEMP/preview-index.html" + curl -fsS http://127.0.0.1:8080/catalog/index.json | grep 'SunshineStream' + + comment-preview: + name: Post the preview command + if: >- + github.event_name == 'pull_request' && + github.event.pull_request.head.repo.id == github.event.pull_request.base.repo.id + needs: verify-preview + uses: ./.github/workflows/jekyll-preview-comment.yml + permissions: + contents: read + actions: read + pull-requests: write + + compatibility: + name: Check Jekyll 3 compatibility + runs-on: ubuntu-latest + permissions: + contents: read + env: + JEKYLL_VERSION: '~> 3.10.0' + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Ruby + uses: ruby/setup-ruby@f9c4492e86def3e644ab32a0ef185eda5b0c20d0 # v1.342.0 + with: + ruby-version: '3.3' + bundler-cache: true + + - name: Build and verify the root site + run: | + bundle exec jekyll build --source example --destination _site/root --config example/_config.yml + ruby script/verify-preview.rb _site/root '' https://app.lizardbyte.dev/ https://example.org + + - name: Build and verify a nested preview + env: + JEKYLL_SOURCE: ${{ github.workspace }}/example + CONFIG_FILES: example/_config.yml,example/_preview.yml + PREVIEW: 'true' + run: | + bundle exec ruby script/build-site.rb + ruby script/verify-preview.rb "$RUNNER_TEMP/jackal-preview/previews/42/ThemerrDB" \ + /previews/42/ThemerrDB /previews/42 https://preview.example.org + grep -F 'url=/previews/42/ThemerrDB/' "$RUNNER_TEMP/jackal-preview/index.html" + + - name: Check the preview comment and build the gem + run: | + node --test script/preview.test.cjs + gem build jekyll-theme-jackal.gemspec diff --git a/.github/workflows/jekyll-build.yml b/.github/workflows/jekyll-build.yml new file mode 100644 index 0000000..3d3eaee --- /dev/null +++ b/.github/workflows/jekyll-build.yml @@ -0,0 +1,140 @@ +--- +name: Build Jekyll site +permissions: {} + +on: + workflow_call: + inputs: + ruby_version: + description: Ruby version for the site build + type: string + default: '4.0' + source_dir: + description: Jekyll source directory, relative to the caller's checkout + type: string + default: '.' + bundle_dir: + description: Directory containing the site's Gemfile, relative to the caller's checkout + type: string + default: '.' + config_files: + description: Optional comma-separated Jekyll config files, relative to bundle_dir + type: string + default: '' + site_artifact: + description: Optional input artifact from an earlier job in this run, overlaid on source_dir + type: string + default: '' + extract_archive: + description: Optional ZIP, TAR, or TAR.GZ filename inside site_artifact + type: string + default: '' + upload_pages: + description: Package the rendered site for GitHub Pages on non-PR runs + type: boolean + default: false + outputs: + preview_artifact: + description: Name of the PR preview artifact + value: ${{ jobs.build.outputs.preview_artifact }} + pages_artifact: + description: Name of the GitHub Pages artifact + value: ${{ jobs.build.outputs.pages_artifact }} + +jobs: + build: + name: Build site + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + preview_artifact: ${{ steps.names.outputs.preview }} + pages_artifact: ${{ steps.names.outputs.pages }} + env: + SITE_SOURCE: ${{ inputs.source_dir }} + BUNDLE_DIR: ${{ inputs.bundle_dir }} + CONFIG_FILES: ${{ inputs.config_files }} + SITE_ARTIFACT: ${{ inputs.site_artifact }} + EXTRACT_ARCHIVE: ${{ inputs.extract_archive }} + BUILD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + PREVIEW: ${{ github.event_name == 'pull_request' }} + UPLOAD_PAGES: >- + ${{ inputs.upload_pages && github.ref_name == github.event.repository.default_branch && + contains(fromJSON('["push","schedule","workflow_dispatch"]'), github.event_name) }} + steps: + - name: Checkout site at the build commit + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ env.BUILD_SHA }} + path: project + persist-credentials: false + + - name: Checkout the reusable workflow tools + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: ${{ job.workflow_repository }} + ref: ${{ job.workflow_sha }} + path: jackal-tools + persist-credentials: false + + - name: Download generated site input + if: inputs.site_artifact != '' + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: ${{ inputs.site_artifact }} + path: ${{ runner.temp }}/jackal-generated + + - name: Prepare Jekyll input + id: prepare + run: python3 jackal-tools/script/prepare-site-input.py + + - name: Set up Ruby + uses: ruby/setup-ruby@f9c4492e86def3e644ab32a0ef185eda5b0c20d0 # v1.342.0 + with: + ruby-version: ${{ inputs.ruby_version }} + working-directory: ${{ steps.prepare.outputs.bundle_dir }} + bundler-cache: true + + - name: Build with the site's bundle + working-directory: ${{ steps.prepare.outputs.bundle_dir }} + env: + JEKYLL_ENV: production + JEKYLL_SOURCE: ${{ steps.prepare.outputs.source_dir }} + run: bundle exec ruby "$GITHUB_WORKSPACE/jackal-tools/script/build-site.rb" + + - name: Name the build artifacts + id: names + run: | + if [[ "$PREVIEW" == 'true' ]]; then + echo "preview=jackal-preview-${BUILD_SHA}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT" + fi + if [[ "$UPLOAD_PAGES" == 'true' ]]; then + echo "pages=github-pages-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT" + fi + + - name: Upload the rendered preview + if: steps.names.outputs.preview != '' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: ${{ steps.names.outputs.preview }} + path: ${{ runner.temp }}/jackal-preview/ + include-hidden-files: true + if-no-files-found: error + retention-days: 14 + + - name: Write the preview command to the run summary + if: steps.names.outputs.preview != '' + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const { formatPreview } = require('./jackal-tools/script/preview.cjs') + await core.summary.addRaw(formatPreview(context.repo, context.runId, + process.env.BUILD_SHA, process.env.GITHUB_RUN_ATTEMPT)).write() + + - name: Package the site for GitHub Pages + if: steps.names.outputs.pages != '' + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + name: ${{ steps.names.outputs.pages }} + path: ${{ runner.temp }}/jackal-site + include-hidden-files: true diff --git a/.github/workflows/jekyll-preview-comment.yml b/.github/workflows/jekyll-preview-comment.yml new file mode 100644 index 0000000..30e7f5f --- /dev/null +++ b/.github/workflows/jekyll-preview-comment.yml @@ -0,0 +1,38 @@ +--- +name: Comment with the Jekyll preview +permissions: {} + +on: + workflow_call: + workflow_run: + workflows: [Theme CI] + types: [completed] + +jobs: + comment: + if: >- + (github.event_name == 'pull_request' && + github.event.pull_request.head.repo.id == github.event.pull_request.base.repo.id) || + (github.event_name == 'workflow_run' && + github.event.workflow_run.event == 'pull_request' && + github.event.workflow_run.conclusion == 'success') + runs-on: ubuntu-latest + permissions: + contents: read + actions: read + pull-requests: write + steps: + - name: Checkout the comment workflow tools + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: ${{ job.workflow_repository }} + ref: ${{ job.workflow_sha }} + path: jackal-tools + persist-credentials: false + + - name: Post or update the preview comment + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const { reportPreview } = require('./jackal-tools/script/preview.cjs') + await reportPreview({ github, context }) diff --git a/.gitignore b/.gitignore index e3f4af3..1196f87 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,11 @@ # JetBrains IDEs .idea/ + +# Local builds and Bundler state +.bundle/ +.jekyll-cache/ +.jekyll-metadata +.sass-cache/ +_site/ +/Gemfile.lock +*.gem diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..fa02953 --- /dev/null +++ b/Gemfile @@ -0,0 +1,11 @@ +source "https://rubygems.org" + +gemspec + +# Set JEKYLL_VERSION=~>3.10.0 to test the GitHub Pages generation of Jekyll. +gem "jekyll", ENV.fetch("JEKYLL_VERSION", "~> 4.4.0") +# These libraries moved out of the default gem set in Ruby 3.4. +gem "base64", "~> 0.3" +gem "bigdecimal", ">= 3.0", "< 5" +gem "kramdown-parser-gfm", "~> 1.1" +gem "webrick", "~> 1.9" diff --git a/README.md b/README.md index eaabf03..6a5a6f9 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,128 @@ alt="LizardByte icon" width="256" /> -

repo-name

-

Repo description. This should exactly match the description in GitHub.

+

Jackal

+

A shared Jekyll theme for organizations and their project sites.

-
- SonarCloud -
+Jackal provides product landing pages, a project hub, articles, a blog index, and wide catalog pages. +Sites choose their own branding, navigation, content, and deployment paths. The theme provides +the shared page structure, responsive components, and system, light, and dark color modes. + +## Preview + +From the theme checkout, install Ruby and Bundler, then run: + +```sh +bundle install +bundle exec jekyll serve --source example --config example/_config.yml +``` + +Open the address printed by Jekyll to preview the Sunshine, Themerr, and Koko examples, +the blog, and the filterable release catalog. Product artwork in the examples is served +by the original sites. Example content and assets are separate from the theme package. + +For a PR, copy the preview command from the CI run summary or preview comment. +It serves the files GitHub already built. See [Build and preview a Jackal site](docs/build-and-preview.md) +for the reusable workflow, GitHub Pages publishing, and generated catalogs. + +## Use Jackal + +For a Jekyll build in GitHub Actions or on your machine, add Jackal to the site's +`Gemfile`. Use a tag or commit that contains the theme: + +```ruby +gem "jekyll-theme-jackal", git: "https://github.com/LizardByte/jackal.git", ref: "YOUR_THEME_REF" +``` + +Set `theme: jekyll-theme-jackal` in `_config.yml` and run `bundle install`. +During development, use `path: "../jackal"` in place of `git:` and `ref:`. + +GitHub Pages' branch builds can instead use +[`jekyll-remote-theme`](https://github.com/benbalter/jekyll-remote-theme). +Set `remote_theme: LizardByte/jackal@YOUR_THEME_REF`, enable `jekyll-remote-theme` +in `plugins`, and omit `theme`. Jackal's layouts require no custom plugins. + +## Configure a site + +```yaml +theme: jekyll-theme-jackal +title: ThemerrDB +description: Browse themes for your media library. +url: https://themerr.lizardbyte.dev +baseurl: /ThemerrDB + +jackal: + logo: /assets/project-logo.svg + icon: /assets/favicon.svg + styles: + - /assets/project.css + nav: + - label: Browse + url: / + - label: Resources + items: + - label: Themerr + url: https://themerr.lizardbyte.dev/ + - label: LizardByte blog + url: /blog/ + scope: umbrella + umbrella: + name: LizardByte + url: https://app.lizardbyte.dev/ + logo: /assets/lizardbyte-wordmark.svg + footer: + - label: Explore projects + url: / + scope: umbrella + - label: Get support + url: /support/ + scope: umbrella + copyright: LizardByte +``` + +- Use an empty `baseurl` for a domain root. Set a subpath such as `/ThemerrDB` for a + project site. Local links and assets automatically use the consumer's `baseurl`. +- Set `jackal.umbrella.url` to a full origin when the parent site is on another domain. + Use `/` for the root of the same origin, or a path such as `/previews/42` when a + preview hosts the umbrella site there. Links marked `scope: umbrella` use that + URL, independently of the project's own `baseurl`. +- `jackal.umbrella.logo` is a project asset unless it is an absolute URL or + `jackal.umbrella.logo_scope: umbrella` is set. If `jackal.umbrella` is omitted, + the footer displays the site's own name. +- Set `jackal.name` to override the displayed site name. Set `jackal.styles` and + `jackal.scripts` for site-wide assets. Pages can also specify their own + `styles` and `scripts` lists in front matter. +- Adjust the theme tokens in your stylesheet. Set `--jackal-accent`, + `--jackal-on-accent`, and `--jackal-accent-soft` together so buttons and links + remain readable in both modes. See [Themerr's example palette](example/assets/example/themerr.css). + +## Layouts + +- `home` displays a hero, content, sections, and recent posts. Set + `show_posts: false` to hide the post list, or use `posts_title` and + `posts_limit` to customize it. +- `product` displays a hero, page content, and reusable sections. Optional + `hero.image` fields include `dark_src`, `width`, `height`, and `caption`. + Set `alt` to describe informative images. +- `page` and `post` provide a reading layout. Use `blog` for a post index. +- `catalog` provides a full-width layout for a data browser. Catalogs can use the + theme's grid, table, and toolbar styles with their own data and JavaScript. +- `jackal` provides the base layout for a custom page. + +Product and home pages build their content using these section types: + +- `cards` for features, linked projects, or platform downloads. +- `gallery` for screenshots, with optional alternate images for dark mode. +- `faq` for expandable questions and answers. +- `callout` for a highlighted action such as sponsorship or installation help. +- `custom` for a site-owned template in `_includes`. Set `template` to its + filename and read any section fields with `include.section`. + +See the [Sunshine example](example/sunshine.md) and [Themerr example](example/themerr.md) +for concrete front matter. Use [the catalog example](example/catalog/index.html) +as a starting point for a project with its own generated data. + +When migrating a site, keep its existing `url`, `baseurl`, permalinks, feeds, and redirects. +Keep generated data, release assets, and downloads at their existing public paths. +Build and compare the new output before changing a site's publishing workflow. diff --git a/_includes/jackal/actions.html b/_includes/jackal/actions.html new file mode 100644 index 0000000..e3d5ad7 --- /dev/null +++ b/_includes/jackal/actions.html @@ -0,0 +1,10 @@ +{% if include.actions.size > 0 %} +
+ {% for jackal_action in include.actions %} + + {{- jackal_action.label | escape -}} + + {% endfor %} +
+{% endif %} diff --git a/_includes/jackal/footer.html b/_includes/jackal/footer.html new file mode 100644 index 0000000..6648f9f --- /dev/null +++ b/_includes/jackal/footer.html @@ -0,0 +1,31 @@ + diff --git a/_includes/jackal/head.html b/_includes/jackal/head.html new file mode 100644 index 0000000..421d964 --- /dev/null +++ b/_includes/jackal/head.html @@ -0,0 +1,24 @@ + + + + {% assign jackal_title = site.jackal.name | default: site.title %} + {% assign jackal_description = page.description | default: page.hero.description | default: site.description %} + {% if page.title and page.title != jackal_title %}{{ page.title | escape }} · {% endif %}{{ jackal_title | escape }} + {% if jackal_description %} + + {% endif %} + {% if site.url and site.url != empty %} + + {% endif %} + {% if site.jackal.icon %} + + {% endif %} + + + {% for jackal_style in site.jackal.styles %} + + {% endfor %} + {% for jackal_style in page.styles %} + + {% endfor %} + diff --git a/_includes/jackal/header.html b/_includes/jackal/header.html new file mode 100644 index 0000000..a17e93e --- /dev/null +++ b/_includes/jackal/header.html @@ -0,0 +1,40 @@ +
+
+ + {% if site.jackal.logo %} + + {% endif %} + {{ site.jackal.name | default: site.title | escape }} + + {% if site.jackal.nav.size > 0 %} + + {% endif %} + +
+
diff --git a/_includes/jackal/hero.html b/_includes/jackal/hero.html new file mode 100644 index 0000000..8af3515 --- /dev/null +++ b/_includes/jackal/hero.html @@ -0,0 +1,14 @@ +{% assign jackal_hero = include.hero %} +
+
+

{{ jackal_hero.title | default: page.title | default: site.title | escape }}

+ {% assign jackal_hero_description = jackal_hero.description | default: page.description %} + {% if jackal_hero_description %} +

{{ jackal_hero_description | escape }}

+ {% endif %} + {% include jackal/actions.html actions=jackal_hero.actions %} +
+ {% if jackal_hero.image.src %} + {% include jackal/media.html image=jackal_hero.image eager=true %} + {% endif %} +
diff --git a/_includes/jackal/media.html b/_includes/jackal/media.html new file mode 100644 index 0000000..58a5d72 --- /dev/null +++ b/_includes/jackal/media.html @@ -0,0 +1,13 @@ +{% assign jackal_image = include.image %} +
+ + {% if jackal_image.dark_src %} + {{ jackal_image.alt | escape }} + {% endif %} + {% if jackal_image.caption %}
{{ jackal_image.caption | escape }}
{% endif %} +
diff --git a/_includes/jackal/nav-link.html b/_includes/jackal/nav-link.html new file mode 100644 index 0000000..1a3fe28 --- /dev/null +++ b/_includes/jackal/nav-link.html @@ -0,0 +1,5 @@ +{%- capture jackal_nav_url -%}{% include jackal/url.html url=include.link.url scope=include.link.scope %}{%- endcapture -%} +{%- assign jackal_nav_current = page.url | relative_url | escape -%} + + {{- include.link.label | escape -}} + diff --git a/_includes/jackal/page-header.html b/_includes/jackal/page-header.html new file mode 100644 index 0000000..d0b816a --- /dev/null +++ b/_includes/jackal/page-header.html @@ -0,0 +1,4 @@ +
+

{{ page.title | default: site.title | escape }}

+ {% if page.description %}

{{ page.description | escape }}

{% endif %} +
diff --git a/_includes/jackal/post-grid.html b/_includes/jackal/post-grid.html new file mode 100644 index 0000000..009f4b3 --- /dev/null +++ b/_includes/jackal/post-grid.html @@ -0,0 +1,12 @@ +
+ {% assign jackal_post_limit = include.limit | default: include.posts.size %} + {% for jackal_post in include.posts limit: jackal_post_limit %} +
+ +

{{ jackal_post.title | escape }}

+

{{ jackal_post.description | default: jackal_post.excerpt | strip_html | strip_newlines | escape }}

+
+ {% endfor %} +
diff --git a/_includes/jackal/sections.html b/_includes/jackal/sections.html new file mode 100644 index 0000000..2e669b8 --- /dev/null +++ b/_includes/jackal/sections.html @@ -0,0 +1,38 @@ +{% for jackal_section in include.sections %} +
+ {% if jackal_section.title %}

{{ jackal_section.title | escape }}

{% endif %} + {% if jackal_section.description %}

{{ jackal_section.description | escape }}

{% endif %} + {% case jackal_section.type %} + {% when 'cards' %} +
+ {% for jackal_card in jackal_section.items %} +
+

{{ jackal_card.title | escape }}

+ {% if jackal_card.description %}
{{ jackal_card.description | markdownify }}
{% endif %} + {% include jackal/actions.html actions=jackal_card.actions %} +
+ {% endfor %} +
+ {% when 'gallery' %} +
+ {% for jackal_gallery_image in jackal_section.items %} + {% include jackal/media.html image=jackal_gallery_image %} + {% endfor %} +
+ {% when 'faq' %} +
+ {% for jackal_question in jackal_section.items %} +
+ {{ jackal_question.question | escape }} +
{{ jackal_question.answer | markdownify }}
+
+ {% endfor %} +
+ {% when 'callout' %} + {% include jackal/actions.html actions=jackal_section.actions %} + {% when 'custom' %} + {% include {{ jackal_section.template }} section=jackal_section %} + {% endcase %} +
+{% endfor %} diff --git a/_includes/jackal/url.html b/_includes/jackal/url.html new file mode 100644 index 0000000..e41372f --- /dev/null +++ b/_includes/jackal/url.html @@ -0,0 +1,19 @@ +{%- assign jackal_url = include.url | default: '' | strip -%} +{%- assign jackal_url_start = jackal_url | slice: 0, 1 -%} +{%- assign jackal_url_pair = jackal_url | slice: 0, 2 -%} +{%- assign jackal_url_scheme = jackal_url | split: ':' | first -%} +{%- if jackal_url == empty or jackal_url contains '://' or jackal_url_start == '#' or jackal_url_start == '?' + or jackal_url_pair == '//' or jackal_url_scheme == 'mailto' or jackal_url_scheme == 'tel' -%} + {{- jackal_url | escape -}} +{%- elsif include.scope == 'umbrella' -%} + {%- assign jackal_umbrella_root = site.jackal.umbrella.url | default: '/' | strip -%} + {%- assign jackal_umbrella_root_end = jackal_umbrella_root | slice: -1, 1 -%} + {%- if jackal_url_start == '/' -%} + {%- assign jackal_url = jackal_url | remove_first: '/' -%} + {%- endif -%} + {{- jackal_umbrella_root | escape -}} + {%- unless jackal_umbrella_root_end == '/' -%}/{%- endunless -%} + {{- jackal_url | escape -}} +{%- else -%} + {{- jackal_url | relative_url | escape -}} +{%- endif -%} diff --git a/_layouts/blog.html b/_layouts/blog.html new file mode 100644 index 0000000..5f8b1e0 --- /dev/null +++ b/_layouts/blog.html @@ -0,0 +1,8 @@ +--- +layout: jackal +--- +
+ {% include jackal/page-header.html %} +
{{ content }}
+ {% include jackal/post-grid.html posts=site.posts %} +
diff --git a/_layouts/catalog.html b/_layouts/catalog.html new file mode 100644 index 0000000..ff9ddb6 --- /dev/null +++ b/_layouts/catalog.html @@ -0,0 +1,7 @@ +--- +layout: jackal +--- +
+ {% include jackal/page-header.html %} + {{ content }} +
diff --git a/_layouts/home.html b/_layouts/home.html new file mode 100644 index 0000000..fb1f805 --- /dev/null +++ b/_layouts/home.html @@ -0,0 +1,19 @@ +--- +layout: jackal +--- +{% include jackal/hero.html hero=page.hero %} + +{% assign jackal_home_body = content | strip %} +{% if jackal_home_body != empty %} +
{{ content }}
+{% endif %} + +{% include jackal/sections.html sections=page.sections %} + +{% if site.posts.size > 0 and page.show_posts != false %} +
+

{{ page.posts_title | default: 'Latest news' | escape }}

+ {% assign jackal_home_post_limit = page.posts_limit | default: 3 %} + {% include jackal/post-grid.html posts=site.posts limit=jackal_home_post_limit %} +
+{% endif %} diff --git a/_layouts/jackal.html b/_layouts/jackal.html new file mode 100644 index 0000000..8d29d9f --- /dev/null +++ b/_layouts/jackal.html @@ -0,0 +1,18 @@ + + + {% include jackal/head.html %} + + Skip to content + {% include jackal/header.html %} +
+ {{ content }} +
+ {% include jackal/footer.html %} + {% for jackal_script in site.jackal.scripts %} + + {% endfor %} + {% for jackal_script in page.scripts %} + + {% endfor %} + + diff --git a/_layouts/page.html b/_layouts/page.html new file mode 100644 index 0000000..58ff34b --- /dev/null +++ b/_layouts/page.html @@ -0,0 +1,7 @@ +--- +layout: jackal +--- +
+ {% include jackal/page-header.html %} +
{{ content }}
+
diff --git a/_layouts/post.html b/_layouts/post.html new file mode 100644 index 0000000..00bd04d --- /dev/null +++ b/_layouts/post.html @@ -0,0 +1,11 @@ +--- +layout: jackal +--- +
+ {% include jackal/page-header.html %} +

+ + {% if page.author %} · {{ page.author | escape }}{% endif %} +

+
{{ content }}
+
diff --git a/_layouts/product.html b/_layouts/product.html new file mode 100644 index 0000000..56cce7a --- /dev/null +++ b/_layouts/product.html @@ -0,0 +1,11 @@ +--- +layout: jackal +--- +{% include jackal/hero.html hero=page.hero %} + +{% assign jackal_product_body = content | strip %} +{% if jackal_product_body != empty %} +
{{ content }}
+{% endif %} + +{% include jackal/sections.html sections=page.sections %} diff --git a/assets/jackal/jackal.css b/assets/jackal/jackal.css new file mode 100644 index 0000000..de56171 --- /dev/null +++ b/assets/jackal/jackal.css @@ -0,0 +1,317 @@ +:root { + color-scheme: light dark; + --jackal-paper: light-dark(#f7f5ee, #171715); + --jackal-surface: light-dark(#fffdf7, #232320); + --jackal-muted-surface: light-dark(#eeeae0, #292824); + --jackal-ink: light-dark(#22221e, #f5f1e8); + --jackal-muted: light-dark(#605d52, #c8c1b1); + --jackal-border: light-dark(#d6cfc0, #49463d); + --jackal-accent: light-dark(#9b3f1c, #ffb085); + --jackal-on-accent: light-dark(#fffdf7, #261106); + --jackal-accent-soft: light-dark(#f8e6da, #37271e); + --jackal-max-width: 74rem; + --jackal-prose-width: 67ch; + --jackal-gutter: clamp(1.25rem, 4vw, 3rem); + --jackal-radius: 1rem; + --jackal-font: system-ui, -apple-system, "Segoe UI", sans-serif; +} + +:root[data-jackal-theme="light"] { color-scheme: light; } +:root[data-jackal-theme="dark"] { color-scheme: dark; } + +body { + margin: 0; + min-width: 0; + background: var(--jackal-paper); + color: var(--jackal-ink); + font: 1rem/1.65 var(--jackal-font); +} + +body, .jackal-header, .jackal-main, .jackal-footer { box-sizing: border-box; } +a { color: var(--jackal-accent); text-underline-offset: 0.2em; } +a:hover { text-decoration-thickness: 0.13em; } +:focus-visible { outline: 2px solid var(--jackal-accent); outline-offset: 4px; } +[id] { scroll-margin-top: 2rem; } + +.jackal-wrap { + box-sizing: border-box; + width: min(100%, var(--jackal-max-width)); + margin-inline: auto; + padding-inline: var(--jackal-gutter); +} + +.jackal-main { min-height: 56vh; padding-bottom: clamp(3rem, 9vw, 8rem); } + +.jackal-sr-only, .jackal-skip:not(:focus) { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip-path: inset(50%); + white-space: nowrap; +} + +.jackal-skip:focus { + position: absolute; + z-index: 3; + inset: 0 auto auto 0; + padding: 0.75rem 1rem; + background: var(--jackal-surface); +} + +.jackal-header { border-bottom: 1px solid var(--jackal-border); } + +.jackal-header__inner { + display: flex; + align-items: center; + flex-wrap: wrap; + gap: 0.6rem 1.5rem; + min-height: 4.75rem; + padding-block: 0.75rem; +} + +.jackal-brand { + display: inline-flex; + align-items: center; + gap: 0.65rem; + color: var(--jackal-ink); + font-size: 1.22rem; + font-weight: 800; + letter-spacing: -0.05em; + text-decoration: none; +} + +.jackal-brand img { object-fit: contain; } +.jackal-nav { margin-inline-start: auto; } + +.jackal-nav ul { + margin: 0; + padding: 0; + list-style: none; +} + +.jackal-nav__list { + display: flex; + align-items: baseline; + flex-wrap: wrap; + gap: 0.25rem 1.5rem; +} + +.jackal-nav a, .jackal-nav summary, .jackal-footer nav a { + color: var(--jackal-ink); + font-size: 0.9rem; + font-weight: 650; + text-decoration: none; +} + +.jackal-nav a:hover, .jackal-nav a[aria-current="page"], .jackal-footer nav a:hover { + color: var(--jackal-accent); + text-decoration: underline; +} + +.jackal-nav__group { position: relative; } +.jackal-nav summary, .jackal-faq summary { cursor: pointer; } + +.jackal-nav .jackal-nav__dropdown { + position: absolute; + z-index: 2; + top: calc(100% + 0.35rem); + inset-inline-end: 0; + width: max-content; + max-width: 80vw; + padding: 0.5rem; + border: 1px solid var(--jackal-border); + border-radius: 0.75rem; + background: var(--jackal-surface); +} + +.jackal-nav__dropdown a { display: block; padding: 0.4rem 0.65rem; } +.jackal-theme-control { margin-inline-start: auto; } +.jackal-nav + .jackal-theme-control { margin-inline-start: 0; } + +.jackal-theme-control select, .jackal-input { + box-sizing: border-box; + min-height: 2.25rem; + padding: 0.4rem 0.65rem; + border: 1px solid var(--jackal-border); + border-radius: 0.6rem; + background: var(--jackal-surface); + color: var(--jackal-ink); + font: inherit; +} + +.jackal-theme-control select { font-size: 0.85rem; } +.jackal-input { padding: 0.65rem 0.8rem; width: min(100%, 30rem); } + +.jackal-hero { + display: grid; + align-items: center; + gap: clamp(2rem, 5vw, 4.5rem); + padding-block: clamp(3.5rem, 8vw, 7rem); +} + +.jackal-hero--with-image { grid-template-columns: minmax(0, 0.95fr) minmax(0, 1.05fr); } + +.jackal-main h1, .jackal-main h2, .jackal-main h3 { + line-height: 1.05; + letter-spacing: -0.041em; + text-wrap: balance; +} + +.jackal-hero h1, .jackal-page-header h1 { margin: 0; font-size: clamp(2.85rem, 7vw, 5.8rem); } +.jackal-hero h1 { max-width: 15ch; } +.jackal-hero__copy > :last-child, .jackal-page-header > :last-child { margin-bottom: 0; } +.jackal-main h2 { margin: 0 0 1.4rem; font-size: clamp(1.85rem, 4.5vw, 3rem); } +.jackal-main h3 { margin: 0; font-size: 1.35rem; } + +.jackal-lede { + max-width: 56ch; + margin-block: 1.2rem 1.75rem; + color: var(--jackal-muted); + font-size: clamp(1.05rem, 2.4vw, 1.32rem); + line-height: 1.55; +} + +.jackal-actions { display: flex; flex-wrap: wrap; gap: 0.65rem; margin-top: 1.25rem; } + +.jackal-button { + display: inline-flex; + align-items: center; + justify-content: center; + box-sizing: border-box; + min-height: 2.75rem; + padding: 0.55rem 1.1rem; + border: 1px solid var(--jackal-border); + border-radius: 2rem; + background: var(--jackal-surface); + color: var(--jackal-ink); + font-size: 0.95rem; + font-weight: 680; + text-decoration: none; +} + +.jackal-button--primary { + border-color: var(--jackal-accent); + background: var(--jackal-accent); + color: var(--jackal-on-accent); +} + +.jackal-button:hover { text-decoration: underline; } + +.jackal-section + .jackal-section { margin-top: clamp(3rem, 7vw, 6rem); } +.jackal-section h2 + .jackal-lede { margin-top: -0.6rem; } + +.jackal-section--callout { + width: min(calc(100% - 2 * var(--jackal-gutter)), calc(var(--jackal-max-width) - 2 * var(--jackal-gutter))); + padding: clamp(1.5rem, 5vw, 3rem); + border: 1px solid var(--jackal-border); + border-radius: var(--jackal-radius); + background: var(--jackal-accent-soft); +} + +.jackal-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)); + gap: 1rem; +} + +.jackal-card { + display: flex; + flex-direction: column; + align-items: start; + gap: 0.75rem; + min-width: 0; + padding: clamp(1rem, 3vw, 1.6rem); + border: 1px solid var(--jackal-border); + border-radius: var(--jackal-radius); + background: var(--jackal-surface); +} + +.jackal-card p { margin: 0; color: var(--jackal-muted); } +.jackal-card .jackal-actions { margin-top: auto; padding-top: 0.25rem; } +.jackal-card .jackal-prose > :first-child { margin-top: 0; } +.jackal-card .jackal-prose > :last-child { margin-bottom: 0; } + +.jackal-media { min-width: 0; margin: 0; } + +.jackal-media img { + display: block; + box-sizing: border-box; + width: 100%; + height: auto; + border: 1px solid var(--jackal-border); + border-radius: var(--jackal-radius); + background: var(--jackal-surface); +} + +.jackal-media img.jackal-media__dark { display: none; } + +:root[data-jackal-theme="dark"] .jackal-media img.jackal-media__light { display: none; } +:root[data-jackal-theme="dark"] .jackal-media img.jackal-media__dark { display: block; } + +@media (prefers-color-scheme: dark) { + :root:not([data-jackal-theme="light"]) .jackal-media img.jackal-media__light { display: none; } + :root:not([data-jackal-theme="light"]) .jackal-media img.jackal-media__dark { display: block; } +} + +.jackal-media figcaption, .jackal-meta { margin-top: 0.5rem; color: var(--jackal-muted); font-size: 0.9rem; } +.jackal-faq details { max-width: 52rem; padding-block: 0.8rem; border-bottom: 1px solid var(--jackal-border); } +.jackal-faq summary { font-weight: 700; } +.jackal-faq details > div { margin-inline-start: 1.15rem; } + +.jackal-reading { max-width: calc(51rem + 2 * var(--jackal-gutter)); } +.jackal-page-header { margin-block: clamp(2rem, 6vw, 4.75rem) 1.5rem; } +.jackal-page-header h1 { font-size: clamp(2.4rem, 6vw, 4.75rem); } +.jackal-prose { max-width: var(--jackal-prose-width); overflow-wrap: break-word; } +.jackal-prose > h2 { margin-top: 1.6em; font-size: clamp(1.6rem, 4vw, 2.25rem); } +.jackal-prose > h3 { margin-top: 1.55em; } +.jackal-prose > :last-child { margin-bottom: 0; } +.jackal-prose img { max-width: 100%; height: auto; } +.jackal-prose pre { padding: 1rem; overflow: auto; } + +.jackal-prose pre, .jackal-prose :not(pre) > code { + border-radius: 0.4rem; + background: var(--jackal-muted-surface); +} + +.jackal-prose :not(pre) > code { padding: 0.1em 0.28em; } +.jackal-prose blockquote { margin-inline: 0; padding-inline-start: 1rem; border-inline-start: 3px solid var(--jackal-accent); } +.jackal-catalog-toolbar { display: flex; flex-wrap: wrap; align-items: end; gap: 1rem; margin-block: 1.5rem; } +.jackal-catalog-toolbar[hidden] { display: none; } +.jackal-catalog-toolbar label { display: grid; gap: 0.25rem; flex: 1 1 18rem; } +.jackal-table-wrap { overflow-x: auto; border: 1px solid var(--jackal-border); border-radius: var(--jackal-radius); } + +.jackal-table { + width: 100%; + border-collapse: collapse; + background: var(--jackal-surface); + text-align: start; +} + +.jackal-table th, .jackal-table td { padding: 0.8rem 1rem; border-bottom: 1px solid var(--jackal-border); text-align: start; } +.jackal-table th { background: var(--jackal-muted-surface); } +.jackal-table tbody tr:last-child td { border-bottom: 0; } + +.jackal-footer { border-top: 1px solid var(--jackal-border); } + +.jackal-footer__inner { + display: grid; + justify-items: center; + gap: 1rem; + padding-block: 2.5rem; + text-align: center; +} + +.jackal-affiliation, .jackal-footer__name { margin: 0; font-weight: 700; } +.jackal-affiliation { display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: 0.38rem; } +.jackal-affiliation img { display: block; width: auto; height: 1.5rem; max-width: 10rem; object-fit: contain; } +.jackal-footer nav { display: flex; justify-content: center; flex-wrap: wrap; gap: 0.45rem 1.15rem; } +.jackal-footer small { color: var(--jackal-muted); } + +@media (max-width: 46rem) { + .jackal-hero--with-image { grid-template-columns: minmax(0, 1fr); } + .jackal-theme-control, .jackal-nav + .jackal-theme-control { margin-inline-start: auto; } + .jackal-nav { order: 1; flex-basis: 100%; margin-inline-start: 0; } + .jackal-nav .jackal-nav__dropdown { position: static; margin-top: 0.4rem; } + .jackal-nav__list { gap: 0.3rem 1rem; } +} diff --git a/assets/jackal/theme.js b/assets/jackal/theme.js new file mode 100644 index 0000000..5f02501 --- /dev/null +++ b/assets/jackal/theme.js @@ -0,0 +1,37 @@ +(() => { + const modes = ['system', 'light', 'dark']; + const storageKey = 'jackal-color-mode'; + let mode = 'system'; + + try { + const saved = window.localStorage.getItem(storageKey); + if (modes.includes(saved)) mode = saved; + } catch { + // The control still works for this page if storage is unavailable. + } + + function applyMode(value) { + document.documentElement.dataset.jackalTheme = value; + } + + applyMode(mode); + document.addEventListener('DOMContentLoaded', () => { + const control = document.querySelector('[data-jackal-theme-control]'); + const selector = control?.querySelector('[data-jackal-theme]'); + if (!selector) return; + + selector.value = mode; + control.hidden = false; + selector.addEventListener('change', () => { + const next = selector.value; + if (!modes.includes(next)) return; + + applyMode(next); + try { + window.localStorage.setItem(storageKey, next); + } catch { + // Apply the selection even when it cannot be remembered. + } + }); + }); +})(); diff --git a/docs/build-and-preview.md b/docs/build-and-preview.md new file mode 100644 index 0000000..4b28781 --- /dev/null +++ b/docs/build-and-preview.md @@ -0,0 +1,108 @@ +# Build and preview a Jackal site + +Call Jackal's [Jekyll build workflow](../.github/workflows/jekyll-build.yml) from the site repository. +Pin `REF` to a Jackal release or commit. The workflow uses Ruby 4.0 by default and builds +with the site's own Gemfile and lockfile, so each site can select the latest Jekyll and plugins +it supports. Set `ruby_version` if a site needs a different Ruby version. + +## Build and publish + +This example builds a site on pushes to its default branch, on PRs, and when dispatched +manually. The repository must have **Settings → Pages → Source** set to **GitHub Actions** +to publish. Set `url` to the site's domain and `baseurl` to the public path in the +site's Jekyll config. For example, ThemerrDB uses `url: https://themerr.lizardbyte.dev` +and `baseurl: /ThemerrDB`. Leave `baseurl` empty for a domain root. + +```yaml +name: Website +permissions: {} + +on: + pull_request: + push: + branches: [master] + workflow_dispatch: + +jobs: + site: + uses: LizardByte/jackal/.github/workflows/jekyll-build.yml@REF + permissions: + contents: read + with: + upload_pages: true + + deploy: + if: needs.site.outputs.pages_artifact != '' + needs: site + runs-on: ubuntu-latest + permissions: + actions: read + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy the built files + id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 + with: + artifact_name: ${{ needs.site.outputs.pages_artifact }} +``` + +The workflow produces a Pages artifact only for pushes, scheduled runs, or manual +runs on the default branch, with `upload_pages: true`. Add a `schedule` trigger if the +site has a scheduled data update. + +Set `source_dir` for a site located below the checkout root. Use `bundle_dir` if its +Gemfile is in a different directory. Optional `config_files` paths are relative to +the bundle directory and apply from left to right. + +### Generated sites and catalogs + +Have an earlier job build the project data and upload an Actions artifact. Set +`needs` to that job and pass its artifact name to `site_artifact`. The workflow +overlays the contents onto `source_dir` before Jekyll builds. For an artifact that +contains a single archive, set `extract_archive` to its filename. Supported +formats are ZIP, TAR, and compressed TAR (`.tar.gz` or `.tgz`). If the generator +checks out the repository on a PR, use `${{ github.event.pull_request.head.sha || github.sha }}` +as its checkout ref so its data comes from the same commit as the site. + +## Preview a pull request + +Open the CI run summary and copy the PowerShell or Bash/Zsh command. GitHub CLI +downloads the files built from the exact PR head commit and run attempt. Docker +serves those files through Nginx at `http://127.0.0.1:8080`. For projects with a +`baseurl`, the local root redirects to the same subpath used on Pages. Stop the +container with Ctrl+C. The downloaded files remain in the temporary directory +named by the command's `preview` variable. Artifacts are available for up to +14 days. + +### Put the command on the PR + +Add this second workflow to the site's default branch. Set `workflows` to the +first workflow's `name`. The reporter looks up the rendered artifact and +updates one comment on the matching PR. It uses the default-branch workflow, +including when the build came from a fork. + +```yaml +name: Website preview comment +permissions: {} + +on: + workflow_run: + workflows: [Website] + types: [completed] + +jobs: + comment: + if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' + uses: LizardByte/jackal/.github/workflows/jekyll-preview-comment.yml@REF + permissions: + actions: read + contents: read + pull-requests: write +``` + +The build runs with read access. The comment job reads Actions metadata and +never downloads or executes the files being reviewed. diff --git a/docs/jackal-preview.jpg b/docs/jackal-preview.jpg new file mode 100644 index 0000000..97614f7 Binary files /dev/null and b/docs/jackal-preview.jpg differ diff --git a/example/_config.yml b/example/_config.yml new file mode 100644 index 0000000..044b94f --- /dev/null +++ b/example/_config.yml @@ -0,0 +1,43 @@ +--- +theme: jekyll-theme-jackal +title: Jackal Preview +description: Preview the shared Jekyll theme for LizardByte sites. +url: https://example.org +permalink: /:year-:month-:day-:title/ +strict_front_matter: true +liquid: + error_mode: strict + +jackal: + name: Jackal + umbrella: + name: LizardByte + url: https://app.lizardbyte.dev/ + logo: https://sunshine.lizardbyte.dev/assets/lizardbyte.svg + nav: + - label: Home + url: / + - label: Projects + items: + - label: Sunshine + url: /sunshine/ + - label: Themerr + url: /themerr/ + - label: Koko + url: /koko/ + - label: Catalog + url: /catalog/ + - label: Blog + url: /blog/ + - label: GitHub + url: https://github.com/LizardByte/jackal + footer: + - label: Explore projects + url: / + scope: umbrella + - label: Get support + url: /support/ + scope: umbrella + - label: Website source + url: https://github.com/LizardByte/jackal + copyright: LizardByte diff --git a/example/_data/catalog.yml b/example/_data/catalog.yml new file mode 100644 index 0000000..f769977 --- /dev/null +++ b/example/_data/catalog.yml @@ -0,0 +1,10 @@ +--- +- name: Sunshine + organization: SunshineStream + url: https://github.com/SunshineStream/Sunshine/releases +- name: Themerr + organization: Themerr + url: https://github.com/Themerr/Themerr/releases +- name: Koko + organization: KokoStreamTV + url: https://github.com/KokoStreamTV/Koko/releases diff --git a/example/_includes/koko-project.html b/example/_includes/koko-project.html new file mode 100644 index 0000000..cfb9ffa --- /dev/null +++ b/example/_includes/koko-project.html @@ -0,0 +1,3 @@ +
+

See the source code and current work on the Koko repository.

+
diff --git a/example/_posts/2026-01-01-a-home-for-each-project.md b/example/_posts/2026-01-01-a-home-for-each-project.md new file mode 100644 index 0000000..bb43fc4 --- /dev/null +++ b/example/_posts/2026-01-01-a-home-for-each-project.md @@ -0,0 +1,13 @@ +--- +layout: post +title: A home for each project +description: How Jackal brings the project sites together. +author: LizardByte +--- + +Each project can publish its own website and choose its own colors, navigation, and content. +Jackal provides the shared layouts used for the home page, the blog, and the catalog. + +## Find a project + +Visit the [project index]({{ '/' | relative_url }}) to explore the three example sites. diff --git a/example/_preview.yml b/example/_preview.yml new file mode 100644 index 0000000..d4db822 --- /dev/null +++ b/example/_preview.yml @@ -0,0 +1,7 @@ +--- +url: https://preview.example.org +baseurl: /previews/42/ThemerrDB + +jackal: + umbrella: + url: /previews/42 diff --git a/example/about.md b/example/about.md new file mode 100644 index 0000000..ebbf3a7 --- /dev/null +++ b/example/about.md @@ -0,0 +1,9 @@ +--- +layout: page +title: About this preview +permalink: /about/ +--- + +This site demonstrates Jackal's layouts with sample content for LizardByte projects. + +Live builds, releases, and documentation are maintained by the individual projects. diff --git a/example/assets/example/catalog.js b/example/assets/example/catalog.js new file mode 100644 index 0000000..c94e392 --- /dev/null +++ b/example/assets/example/catalog.js @@ -0,0 +1,18 @@ +const toolbar = document.querySelector('[data-catalog-toolbar]'); +const search = toolbar.querySelector('[data-catalog-search]'); +const status = toolbar.querySelector('[data-catalog-status]'); +const rows = [...document.querySelectorAll('[data-catalog-row]')]; + +function updateCatalog() { + const query = search.value.trim().toLowerCase(); + let matches = 0; + for (const row of rows) { + row.hidden = !row.textContent.toLowerCase().includes(query); + if (!row.hidden) matches += 1; + } + status.textContent = matches === 1 ? '1 result' : `${matches} results`; +} + +search.addEventListener('input', updateCatalog); +updateCatalog(); +toolbar.hidden = false; diff --git a/example/assets/example/koko.css b/example/assets/example/koko.css new file mode 100644 index 0000000..d5e5163 --- /dev/null +++ b/example/assets/example/koko.css @@ -0,0 +1,5 @@ +:root { + --jackal-accent: light-dark(#3b3e97, #b9baff); + --jackal-on-accent: light-dark(#f9f9ff, #1a1843); + --jackal-accent-soft: light-dark(#e9e8fb, #2c284a); +} diff --git a/example/assets/example/themerr.css b/example/assets/example/themerr.css new file mode 100644 index 0000000..32910e8 --- /dev/null +++ b/example/assets/example/themerr.css @@ -0,0 +1,5 @@ +:root { + --jackal-accent: light-dark(#961c43, #ff9cb3); + --jackal-on-accent: light-dark(#fff8fa, #300713); + --jackal-accent-soft: light-dark(#f7e5eb, #3a2032); +} diff --git a/example/blog.md b/example/blog.md new file mode 100644 index 0000000..c52352c --- /dev/null +++ b/example/blog.md @@ -0,0 +1,5 @@ +--- +layout: blog +title: Blog +permalink: /blog/ +--- diff --git a/example/catalog/index.html b/example/catalog/index.html new file mode 100644 index 0000000..4b429ad --- /dev/null +++ b/example/catalog/index.html @@ -0,0 +1,31 @@ +--- +layout: catalog +title: Release catalog +description: Browse releases across the LizardByte project organizations. +scripts: + - /assets/example/catalog.js +--- + +
+ + + + + + + {% for project in site.data.catalog %} + + + + + + {% endfor %} + +
Project release links
ProjectOrganizationReleases
{{ project.name | escape }}{{ project.organization | escape }}View {{ project.name | escape }} releases
+
+

Download catalog JSON

diff --git a/example/catalog/index.json b/example/catalog/index.json new file mode 100644 index 0000000..94fb9a5 --- /dev/null +++ b/example/catalog/index.json @@ -0,0 +1,4 @@ +--- +layout: null +--- +{{ site.data.catalog | jsonify }} diff --git a/example/index.md b/example/index.md new file mode 100644 index 0000000..bc55749 --- /dev/null +++ b/example/index.md @@ -0,0 +1,33 @@ +--- +layout: home +title: Jackal +hero: + title: A shared home for LizardByte projects. + description: Explore our self-hosted software, read project news, and browse releases. + actions: + - label: Explore projects + url: '#projects' + primary: true + - label: Browse releases + url: /catalog/ +sections: + - type: cards + id: projects + title: Projects + items: + - title: Sunshine + description: Stream games and apps from your own computer with Moonlight. + actions: + - label: Explore Sunshine + url: /sunshine/ + - title: Themerr + description: Add theme music to your Plex or Jellyfin library. + actions: + - label: Explore Themerr + url: /themerr/ + - title: Koko + description: Bring movies, music, books, and more together in a self-hosted media server. + actions: + - label: Explore Koko + url: /koko/ +--- diff --git a/example/koko.md b/example/koko.md new file mode 100644 index 0000000..3de1b1a --- /dev/null +++ b/example/koko.md @@ -0,0 +1,23 @@ +--- +layout: product +title: Koko +permalink: /koko/ +styles: + - /assets/example/koko.css +hero: + title: Your media. At home. + description: Koko is a self-hosted media server in development for movies, shows, music, books, and podcasts. + actions: + - label: Follow development + url: https://github.com/KokoStreamTV/Koko + primary: true + image: + src: https://koko.lizardbyte.dev/assets/collection.svg + alt: An illustrated movie cover, vinyl record, and book. + width: 680 + height: 580 +sections: + - type: custom + title: Explore the project + template: koko-project.html +--- diff --git a/example/sunshine.md b/example/sunshine.md new file mode 100644 index 0000000..d51facf --- /dev/null +++ b/example/sunshine.md @@ -0,0 +1,46 @@ +--- +layout: product +title: Sunshine +permalink: /sunshine/ +hero: + title: Your games. Your PC. Every screen. + description: Turn your PC into your own game streaming host, then play through Moonlight. + actions: + - label: Get Sunshine + url: '#download' + primary: true + - label: Read the docs + url: https://docs.lizardbyte.dev/projects/sunshine/latest/ + image: + src: https://sunshine.lizardbyte.dev/assets/sunshine-web-ui-light.jpg + dark_src: https://sunshine.lizardbyte.dev/assets/sunshine-web-ui-dark.jpg + alt: Sunshine's welcome screen in a web browser. +sections: + - type: cards + id: download + title: Download Sunshine + description: Install Sunshine on the computer that runs your games. + items: + - title: Windows + description: Get the installer for your host computer. + actions: + - label: Releases + url: https://github.com/SunshineStream/Sunshine/releases/latest + - title: macOS + description: Use a DMG package from the latest release. + actions: + - label: Releases + url: https://github.com/SunshineStream/Sunshine/releases/latest + - title: Linux and FreeBSD + description: Find the installation instructions for your system. + actions: + - label: Installation guide + url: https://docs.lizardbyte.dev/projects/sunshine/latest/ + - type: callout + title: Support Sunshine + description: Help fund ongoing development through LizardByte. + actions: + - label: GitHub Sponsors + url: https://github.com/sponsors/LizardByte + primary: true +--- diff --git a/example/themerr.md b/example/themerr.md new file mode 100644 index 0000000..85d307b --- /dev/null +++ b/example/themerr.md @@ -0,0 +1,32 @@ +--- +layout: product +title: Themerr +permalink: /themerr/ +styles: + - /assets/example/themerr.css +hero: + title: Give your library a soundtrack. + description: Bring theme music to movies and shows in your Plex or Jellyfin library. + actions: + - label: Get Themerr + url: https://github.com/Themerr/Themerr/releases + primary: true + - label: Explore ThemerrDB + url: https://themerr.lizardbyte.dev/ThemerrDB/ + image: + src: https://themerr.lizardbyte.dev/assets/themerr-icon.png + alt: Themerr logo. +sections: + - type: cards + title: Media server support + items: + - title: Plex + description: Add theme music to movies and shows in Plex. + - title: Jellyfin + description: Add theme music to your Jellyfin library. + - type: faq + title: About ThemerrDB + items: + - question: Where do themes come from? + answer: Browse the shared catalog in [ThemerrDB](https://themerr.lizardbyte.dev/ThemerrDB/). +--- diff --git a/jekyll-theme-jackal.gemspec b/jekyll-theme-jackal.gemspec new file mode 100644 index 0000000..2f146a3 --- /dev/null +++ b/jekyll-theme-jackal.gemspec @@ -0,0 +1,14 @@ +# frozen_string_literal: true + +Gem::Specification.new do |spec| + spec.name = "jekyll-theme-jackal" + spec.version = "0.1.0" + spec.authors = ["LizardByte"] + spec.summary = "A shared Jekyll theme for organizations and their project sites." + spec.homepage = "https://github.com/LizardByte/jackal" + spec.files = Dir.chdir(__dir__) do + Dir.glob("{_layouts,_includes,assets}/**/*").select { |path| File.file?(path) } + %w[README.md LICENSE] + end + spec.required_ruby_version = ">= 2.7" + spec.add_runtime_dependency "jekyll", ">= 3.10", "< 5" +end diff --git a/script/build-site.rb b/script/build-site.rb new file mode 100644 index 0000000..713fcf6 --- /dev/null +++ b/script/build-site.rb @@ -0,0 +1,49 @@ +# frozen_string_literal: true + +require "fileutils" +require "jekyll" + +# Load Bundler's Jekyll plugins as the Jekyll executable does. +Jekyll::PluginManager.require_from_bundler + +temp = ENV.fetch("RUNNER_TEMP") +destination = File.join(temp, "jackal-site") +options = { + "source" => ENV.fetch("JEKYLL_SOURCE"), + "destination" => destination, + "incremental" => false, + "strict_front_matter" => true, +} +config_files = ENV.fetch("CONFIG_FILES", "").split(",").map(&:strip) +options["config"] = config_files unless config_files.empty? +site = Jekyll::Site.new(Jekyll.configuration(options)) +Jekyll::Commands::Build.build(site, site.config) + +return unless ENV["PREVIEW"] == "true" + +# GitHub Pages supplies the mount path in production. Replicate that path +# locally without changing the rendered site or its configured URLs. +baseurl = site.config["baseurl"].to_s.sub(%r{/\z}, "") +segments = baseurl.split("/").drop(1) +valid_segment = ->(part) { part.match?(/\A[A-Za-z0-9._~-]+\z/) && !%w[. ..].include?(part) } +unless baseurl.empty? || (baseurl.start_with?("/") && segments.all?(&valid_segment)) + abort "baseurl must be an empty string or a URL path with simple segments" +end + +preview = File.join(temp, "jackal-preview") +if baseurl.empty? + FileUtils.mv(destination, preview) +else + site_path = File.join(preview, *segments) + FileUtils.mkdir_p(File.dirname(site_path)) + FileUtils.mv(destination, site_path) + File.write(File.join(preview, "index.html"), <<~HTML) + + + + Jackal preview + + Open the preview + + HTML +end diff --git a/script/prepare-site-input.py b/script/prepare-site-input.py new file mode 100644 index 0000000..3fb96cc --- /dev/null +++ b/script/prepare-site-input.py @@ -0,0 +1,66 @@ +"""Prepare checkout and generated artifact inputs for the Jekyll build.""" + +import os +import shutil +from pathlib import Path + + +def directory_inside(root, value): + """Resolve an existing directory relative to the checkout.""" + path = (root / value).resolve() + if "\n" in str(path) or "\r" in str(path): + raise SystemExit("A directory path cannot contain line breaks") + if not path.is_relative_to(root) or not path.is_dir(): + raise SystemExit(f"Not a directory inside the checkout: {value!r}") + return path + + +def overlay_generated(source, generated): + """Copy generated regular files into the site's source tree.""" + entries = list(generated.rglob("*")) + for entry in entries: + relative = entry.relative_to(generated) + target = (source / relative).resolve() + if entry.is_symlink() or not target.is_relative_to(source): + raise SystemExit(f"Unsupported generated path: {relative}") + target_parts = target.relative_to(source).parts + if ".git" in relative.parts or ".git" in target_parts: + raise SystemExit(f"Unsupported generated path: {relative}") + shutil.copytree(generated, source, dirs_exist_ok=True) + + +def main(): + """Validate paths and optionally unpack and overlay a same-run artifact.""" + checkout = (Path(os.environ["GITHUB_WORKSPACE"]) / "project").resolve() + source = directory_inside(checkout, os.environ["SITE_SOURCE"]) + bundle = directory_inside(checkout, os.environ["BUNDLE_DIR"]) + archive_name = os.environ["EXTRACT_ARCHIVE"] + temp = Path(os.environ["RUNNER_TEMP"]) + + if os.environ["SITE_ARTIFACT"]: + generated = temp / "jackal-generated" + if archive_name: + archive = generated / archive_name + if Path(archive_name).name != archive_name: + raise SystemExit("extract_archive must be a filename") + if not archive.is_file() or archive.is_symlink(): + raise SystemExit("Archive not found at the artifact root") + generated = temp / "jackal-extracted" + if archive.suffix.lower() == ".zip": + shutil.unpack_archive(archive, generated, format="zip") + elif archive.name.endswith((".tar", ".tar.gz", ".tgz")): + shutil.unpack_archive(archive, generated, filter="data") + else: + raise SystemExit("extract_archive must use ZIP, TAR or TAR.GZ") + overlay_generated(source, generated) + elif archive_name: + raise SystemExit("extract_archive requires site_artifact") + + if not (bundle / "Gemfile").is_file(): + raise SystemExit(f"No Gemfile found in {bundle.relative_to(checkout)}") + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write(f"source_dir={source}\nbundle_dir={bundle}\n") + + +if __name__ == "__main__": + main() diff --git a/script/preview.cjs b/script/preview.cjs new file mode 100644 index 0000000..7fb11df --- /dev/null +++ b/script/preview.cjs @@ -0,0 +1,110 @@ +const OWNER_REPO = /^[A-Za-z0-9_.-]+$/; +const SHA = /^[a-f0-9]{40}$/; +const POSITIVE_INTEGER = /^[1-9][0-9]*$/; +const MARKER = ''; + +function getMainArtifact(sha, attempt) { + if (!SHA.test(sha) || !POSITIVE_INTEGER.test(attempt)) { + throw new Error('Invalid build commit or run attempt'); + } + return `jackal-preview-${sha}-${attempt}`; +} + +function formatPreview({ owner, repo }, runId, sha, attempt) { + if (!OWNER_REPO.test(owner) || !OWNER_REPO.test(repo) || !POSITIVE_INTEGER.test(runId)) { + throw new Error('Invalid repository or run ID'); + } + const artifact = getMainArtifact(sha, attempt); + const download = `gh run download ${runId} --repo ${owner}/${repo} --name ${artifact}`; + const serve = 'docker run --rm -p 127.0.0.1:8080:80 ' + + '--mount "type=bind,source=$preview,target=/usr/share/nginx/html,readonly" nginx:alpine'; + + return [ + MARKER, + '### Preview this build', + '', + `Commit \`${sha}\` · [CI run ${runId}, attempt ${attempt}](https://github.com/${owner}/${repo}/actions/runs/${runId})`, + '', + 'With Docker running and GitHub CLI signed in, paste one command:', + '', + '**PowerShell**', + '', + '```powershell', + '$preview = Join-Path ([IO.Path]::GetTempPath()) ("jackal-" + [guid]::NewGuid()); ' + + `${download} --dir "$preview"; if ($LASTEXITCODE -eq 0) { ${serve} }`, + '```', + '', + '**Bash or Zsh**', + '', + '```sh', + `preview="$(mktemp -d)" && ${download} --dir "$preview" && ${serve}`, + '```', + '', + 'Open [localhost:8080](http://127.0.0.1:8080). Stop the server with Ctrl+C.', + 'The download is retained by GitHub Actions for up to 14 days.', + '', + ].join('\n'); +} + +function sameHead(pull, headRepository, sha) { + return pull.state === 'open' && pull.head.repo?.id === headRepository && pull.head.sha === sha; +} + +async function findPreviewAttempt(github, repository, runId, sha, attempt) { + const exact = getMainArtifact(sha, attempt); + const params = { ...repository, run_id: runId }; + const artifacts = github.rest.actions.listWorkflowRunArtifacts; + const current = await github.paginate(artifacts, { ...params, name: exact }); + if (current.some(item => item.name === exact && !item.expired)) return attempt; + + // Rerunning only failed jobs can reuse the successful build from an + // earlier attempt. Report the attempt that actually produced its files. + const prefix = `jackal-preview-${sha}-`; + const earlier = await github.paginate(artifacts, params); + return earlier.reduce((latest, item) => { + if (item.expired || !item.name.startsWith(prefix)) return latest; + const suffix = item.name.slice(prefix.length); + if (!POSITIVE_INTEGER.test(suffix) || Number(suffix) >= Number(attempt)) return latest; + return Math.max(latest, Number(suffix)); + }, 0); +} + +async function reportPreview({ github, context }) { + const { repo: repository, payload, runId: currentRunId } = context; + const run = payload.workflow_run; + const pull = payload.pull_request; + if (run && (run.event !== 'pull_request' || run.conclusion !== 'success')) return; + if (!run && (!pull || pull.head.repo.id !== pull.base.repo.id)) return; + + const headRepository = run ? run.head_repository : pull.head.repo; + if (!headRepository) return; + const sha = run?.head_sha ?? pull.head.sha; + const runId = run?.id ?? currentRunId; + const attempt = await findPreviewAttempt(github, repository, runId, sha, + run?.run_attempt ?? process.env.GITHUB_RUN_ATTEMPT); + if (!attempt) return; + + // Fork PRs can be absent from workflow_run.pull_requests. Resolve them by + // the actual head repository, branch and commit, never by an artifact field. + const head = run?.head_branch ?? pull.head.ref; + const candidates = pull ? [pull] : await github.paginate(github.rest.pulls.list, { + ...repository, state: 'open', head: `${headRepository.owner.login}:${head}`, + }); + const body = formatPreview(repository, runId, sha, attempt); + for (const candidate of candidates.filter(item => sameHead(item, headRepository.id, sha))) { + const params = { ...repository, issue_number: candidate.number }; + const comments = await github.paginate(github.rest.issues.listComments, params); + const existing = comments.find(comment => + comment.user?.type === 'Bot' && comment.user.login === 'github-actions[bot]' && comment.body?.startsWith(MARKER), + ); + const { data: current } = await github.rest.pulls.get({ ...repository, pull_number: candidate.number }); + if (!sameHead(current, headRepository.id, sha) || existing?.body.trimEnd() === body.trimEnd()) continue; + if (existing) { + await github.rest.issues.updateComment({ ...repository, comment_id: existing.id, body }); + } else { + await github.rest.issues.createComment({ ...params, body }); + } + } +} + +module.exports = { formatPreview, reportPreview }; diff --git a/script/preview.test.cjs b/script/preview.test.cjs new file mode 100644 index 0000000..a102437 --- /dev/null +++ b/script/preview.test.cjs @@ -0,0 +1,91 @@ +const assert = require('node:assert/strict'); +const test = require('node:test'); +const { formatPreview, reportPreview } = require('./preview.cjs'); + +const commit = 'a'.repeat(40); +const repository = { owner: 'Themerr', repo: 'ThemerrDB' }; +const fork = { id: 7, owner: { login: 'contributor' } }; +const pull = { number: 12, state: 'open', head: { repo: fork, sha: commit, ref: 'add-data' } }; +const run = { + event: 'pull_request', conclusion: 'success', id: 45, run_attempt: 2, + head_sha: commit, head_branch: 'add-data', head_repository: fork, pull_requests: [], +}; +const artifact = `jackal-preview-${commit}-2`; + +function workflowRun({ artifacts = [{ name: artifact, expired: false }], comments = [], current = pull } = {}) { + const calls = []; + const context = { repo: repository, payload: { workflow_run: run } }; + const github = { + rest: { + actions: { listWorkflowRunArtifacts: () => {} }, + pulls: { list: () => {}, get: async () => ({ data: current }) }, + issues: { + listComments: () => {}, + createComment: async args => calls.push(['create', args]), + updateComment: async args => calls.push(['update', args]), + }, + }, + async paginate(endpoint, args) { + if (endpoint === this.rest.actions.listWorkflowRunArtifacts) { + assert.equal(args.run_id, 45); + assert.ok(!args.name || args.name === artifact); + return args.name ? artifacts.filter(item => item.name === args.name) : artifacts; + } + if (endpoint === this.rest.pulls.list) { + assert.equal(args.head, 'contributor:add-data'); + return [pull, { ...pull, number: 13, head: { ...pull.head, repo: { id: 8 } } }]; + } + assert.equal(args.issue_number, 12); + return comments; + }, + }; + return { github, context, calls }; +} + +test('the local commands download one specific run attempt and mount it read-only', () => { + const body = formatPreview(repository, 45, commit, 2); + const command = `gh run download 45 --repo Themerr/ThemerrDB --name ${artifact}`; + assert.equal(body.split(command).length - 1, 2); + assert.match(body, /\b127\.0\.0\.1:8080:80\b/); + assert.match(body, /target=\/usr\/share\/nginx\/html,readonly/); + assert.throws(() => formatPreview(repository, '45; echo wrong', commit, 2), /Invalid repository or run ID/); +}); + +test('a fork build can report to the correct PR without PR numbers in the workflow event', async () => { + const inputs = workflowRun(); + await reportPreview(inputs); + assert.equal(inputs.calls.length, 1); + assert.equal(inputs.calls[0][0], 'create'); + assert.equal(inputs.calls[0][1].issue_number, 12); + assert.match(inputs.calls[0][1].body, new RegExp(artifact)); +}); + +test('a run for an outdated head or missing exact artifact does not post a preview', async () => { + for (const options of [ + { current: { ...pull, head: { ...pull.head, sha: 'b'.repeat(40) } } }, + { artifacts: [{ name: `jackal-preview-${'b'.repeat(40)}-2`, expired: false }] }, + { artifacts: [{ name: artifact, expired: true }] }, + ]) { + const inputs = workflowRun(options); + await reportPreview(inputs); + assert.deepEqual(inputs.calls, []); + } +}); + +test('a retry of downstream jobs can report the artifact from the prior build attempt', async () => { + const inputs = workflowRun({ artifacts: [{ name: `jackal-preview-${commit}-1`, expired: false }] }); + await reportPreview(inputs); + assert.match(inputs.calls[0][1].body, new RegExp(`jackal-preview-${commit}-1`)); +}); + +test('only a previous preview comment owned by GitHub Actions is updated', async () => { + const body = '\nPrevious preview'; + const inputs = workflowRun({ comments: [ + { id: 1, user: { type: 'User', login: 'reviewer' }, body }, + { id: 2, user: { type: 'Bot', login: 'github-actions[bot]' }, body }, + ] }); + await reportPreview(inputs); + assert.equal(inputs.calls.length, 1); + assert.equal(inputs.calls[0][0], 'update'); + assert.equal(inputs.calls[0][1].comment_id, 2); +}); diff --git a/script/verify-preview.rb b/script/verify-preview.rb new file mode 100644 index 0000000..f706969 --- /dev/null +++ b/script/verify-preview.rb @@ -0,0 +1,56 @@ +# frozen_string_literal: true + +require "json" + +site_dir, baseurl, umbrella_url, origin = ARGV +abort "Usage: ruby script/verify-preview.rb SITE_DIR BASEURL UMBRELLA_URL ORIGIN" unless origin + +def require_fragment(html, fragment) + abort "Missing rendered fragment: #{fragment}" unless html.include?(fragment) +end + +def read_page(site_dir, path) + html = File.read(File.join(site_dir, path), encoding: "UTF-8") + abort "Unexpected source markup in #{path}" if html.include?("Liquid Exception:") || html.include?("{% include") + html +end + +pages = %w[index.html sunshine/index.html themerr/index.html koko/index.html catalog/index.html + blog/index.html 2026-01-01-a-home-for-each-project/index.html about/index.html] + +pages.each do |path| + html = read_page(site_dir, path) + require_fragment(html, %(href="#{baseurl}/assets/jackal/jackal.css")) + require_fragment(html, %(src="#{baseurl}/assets/jackal/theme.js")) + require_fragment(html, %(href="#{umbrella_url.sub(%r{/$}, "")}/support/")) + public_path = path.delete_suffix("index.html") + require_fragment(html, %(rel="canonical" href="#{origin}#{baseurl}/#{public_path}")) +end + +home = read_page(site_dir, "index.html") +require_fragment(home, %(href="#projects")) +require_fragment(home, %(href="#{baseurl}/sunshine/")) + +sunshine = read_page(site_dir, "sunshine/index.html") +require_fragment(sunshine, "sunshine-web-ui-dark.jpg") +require_fragment(sunshine, %(href="#download")) + +themerr = read_page(site_dir, "themerr/index.html") +require_fragment(themerr, %(href="#{baseurl}/assets/example/themerr.css")) +require_fragment(themerr, %(href="https://themerr.lizardbyte.dev/ThemerrDB/")) + +koko = read_page(site_dir, "koko/index.html") +require_fragment(koko, "See the source code and current work") + +catalog = read_page(site_dir, "catalog/index.html") +require_fragment(catalog, %(src="#{baseurl}/assets/example/catalog.js")) +require_fragment(catalog, %(href="#{baseurl}/catalog/index.json")) + +orgs = JSON.parse(File.read(File.join(site_dir, "catalog/index.json"))).map { |entry| entry.fetch("organization") } +abort "Catalog JSON contains unexpected organizations" unless orgs.sort == %w[KokoStreamTV SunshineStream Themerr] + +%w[assets/jackal/theme.js assets/jackal/jackal.css assets/example/catalog.js].each do |path| + abort "Missing static asset #{path}" unless File.file?(File.join(site_dir, path)) +end + +puts "Verified #{pages.size} pages, their URLs and assets, and the catalog JSON."