Initial commit

.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Package and push to registry repo
+on:
+  push:
+    tags: [ v* ]
+
+env:
+  # the repository to which to push the release version
+  # usually a fork of typst/packages (https://github.com/typst/packages/)
+  # that you have push privileges to
+  REGISTRY_REPO: author/typst-packages
+  # the path within that repo where the "<name>/<version>" directory should be put
+  # for the Typst package registry, keep this as is
+  PATH_PREFIX: packages/preview
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Probe runner package cache
+        uses: awalsh128/cache-apt-pkgs-action@v1
+        with:
+          packages: cargo
+          version: 1.0
+
+      - name: Install just from crates.io
+        uses: baptiste0928/cargo-install@v3
+        with:
+          crate: just
+
+      - name: Setup typst
+        uses: typst-community/setup-typst@v3
+        with:
+          typst-version: latest
+
+      - name: Determine and check package metadata
+        run: |
+          . scripts/setup
+          echo "PKG_NAME=${PKG_PREFIX}" >> "${GITHUB_ENV}"
+          echo "PKG_VERSION=${VERSION}" >> "${GITHUB_ENV}"
+
+          if [[ "${GITHUB_REF_NAME}" != "v${VERSION}" ]]; then
+            echo "package version ${VERSION} does not match release tag ${GITHUB_REF_NAME}" >&2
+            exit 1
+          fi
+
+      - name: Build package
+        run: |
+          just doc
+          just package out
+
+      - name: Checkout package registry
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.REGISTRY_REPO }}
+          token: ${{ secrets.REGISTRY_TOKEN }}
+          path: typst-packages
+
+      - name: Release package
+        run: |
+          mkdir -p "typst-packages/${{ env.PATH_PREFIX }}/$PKG_NAME"
+          mv "out/${PKG_NAME}/${PKG_VERSION}" "typst-packages/${{ env.PATH_PREFIX }}/${PKG_NAME}"
+          rmdir "out/${PKG_NAME}"
+          rmdir out
+
+          GIT_USER_NAME="$(git log -1 --pretty=format:'%an')"
+          GIT_USER_EMAIL="$(git log -1 --pretty=format:'%ae')"
+
+          cd typst-packages
+          git config user.name "${GIT_USER_NAME}"
+          git config user.email "${GIT_USER_EMAIL}"
+          git checkout -b "${PKG_NAME}-${PKG_VERSION}"
+          git add .
+          git commit -m "${PKG_NAME}:${PKG_VERSION}"
+          git push --set-upstream origin "${PKG_NAME}-${PKG_VERSION}"

.github/workflows/tests.yml

@@ -0,0 +1,67 @@
+name: Tests
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tests:
+    strategy:
+      matrix:
+        # add any other Typst versions that your package should support
+        typst-version: ["0.11"]
+        # the docs don't need to build with all versions supported by the package;
+        # the latest one is enough
+        include:
+          - typst-version: "0.11"
+            doc: 1
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Probe runner package cache
+        uses: awalsh128/cache-apt-pkgs-action@v1
+        with:
+          packages: imagemagick cargo
+          version: 1.0
+
+      - name: Install oxipng from crates.io
+        uses: baptiste0928/cargo-install@v3
+        with:
+          crate: oxipng
+
+      - name: Install just from crates.io
+        uses: baptiste0928/cargo-install@v3
+        with:
+          crate: just
+
+      - name: Install typst-test from github
+        uses: baptiste0928/cargo-install@v3
+        with:
+          crate: typst-test
+          git: https://github.com/tingerrr/typst-test.git
+          tag: ci-semi-stable
+
+      - name: Setup typst
+        uses: typst-community/setup-typst@v3
+        with:
+          typst-version: ${{ matrix.typst-version }}
+
+      - name: Run test suite
+        run: just test
+
+      - name: Archive diffs
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: diffs
+          path: |
+            tests/**/diff/*.png
+            tests/**/out/*.png
+          retention-days: 5
+
+      - name: Build docs
+        if: ${{ matrix.doc }}
+        run: just doc

.typstignore

@@ -0,0 +1,16 @@
+# this is not a "standard" ignore file, it's specific to this template's `scripts/package` script
+# list any files here that should not be uploaded to Universe when releasing this package
+
+# if you are used to ignore files, be aware that .typstignore is a bit more limited:
+# - only this file is used; .typstignore files in subdirectories are not considered
+# - patterns must match file/directory names from the beginning: `x.typ` will not match `src/x.typ`
+# - `*` in patterns works, but also matches directory separators: `*.typ` _will_ match `src/x.typ`
+# .git and .typstignore are excluded automatically
+
+.github
+scripts
+tests
+Justfile
+# PDF manuals should be included so that they can be linked, but not their sources
+docs/*
+!docs/*.pdf

CHANGELOG.md

@@ -0,0 +1,13 @@
+# [unreleased](https://github.com/author/my-package/releases/tags/)
+## Added
+
+## Removed
+
+## Changed
+
+## Migration Guide from v0.1.X
+
+---
+
+# [v0.1.0](https://github.com/author/my-package/releases/tags/v0.1.0)
+Initial Release

Justfile

@@ -0,0 +1,42 @@
+root := justfile_directory()
+
+export TYPST_ROOT := root
+
+[private]
+default:
+	@just --list --unsorted
+
+# generate manual
+doc:
+	typst compile docs/manual.typ docs/manual.pdf
+
+# run test suite
+test *args:
+	typst-test run {{ args }}
+
+# update test cases
+update *args:
+	typst-test update {{ args }}
+
+# package the library into the specified destination folder
+package target:
+  ./scripts/package "{{target}}"
+
+# install the library with the "@local" prefix
+install: (package "@local")
+
+# install the library with the "@preview" prefix (for pre-release testing)
+install-preview: (package "@preview")
+
+[private]
+remove target:
+  ./scripts/uninstall "{{target}}"
+
+# uninstalls the library from the "@local" prefix
+uninstall: (remove "@local")
+
+# uninstalls the library from the "@preview" prefix (for pre-release testing)
+uninstall-preview: (remove "@preview")
+
+# run ci suite
+ci: test doc

LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

README.md

@@ -0,0 +1,64 @@
+# The `my-package` Package
+<div align="center">Version 0.1.0</div>
+
+A short description about the project and/or client.
+
+## Template adaptation checklist
+
+- [ ] Fill out `README.md`
+  - Change the `my-package` package name, including code snippets
+  - Check section contents and/or delete sections that don't apply
+- [ ] Check and/or replace `LICENSE` by something that suits your needs
+- [ ] Fill out `typst.toml`
+  - See also the [typst/packages README](https://github.com/typst/packages/?tab=readme-ov-file#package-format)
+- [ ] Adapt Repository URLs in `CHANGELOG.md`
+  - Consider only committing that file with your first release, or removing the "Initial Release" part in the beginning
+- [ ] Adapt or deactivate the release workflow in `.github/workflows/release.yml`
+  - to deactivate it, delete that file or remove/comment out lines 2-4 (`on:` and following)
+  - to use the workflow
+    - [ ] check the values under `env:`, particularly `REGISTRY_REPO`
+    - [ ] if you don't have one, [create a fine-grained personal access token](https://github.com/settings/tokens?type=beta) with [only Contents permission](https://stackoverflow.com/a/75116350/371191) for the `REGISTRY_REPO`
+    - [ ] on this repo, create a secret `REGISTRY_TOKEN` (at `https://github.com/[user]/[repo]/settings/secrets/actions`) that contains the so created token
+
+    if configured correctly, whenever you create a tag `v...`, your package will be pushed onto a branch on the `REGISTRY_REPO`, from which you can then create a pull request against [typst/packages](https://github.com/typst/packages/)
+- [ ] remove/replace the example test case
+- [ ] (add your actual code, docs and tests)
+- [ ] remove this section from the README
+
+## Getting Started
+
+These instructions will get you a copy of the project up and running on the typst web app. Perhaps a short code example on importing the package and a very simple teaser usage.
+
+```typ
+#import "@preview/my-package:0.1.0": *
+
+#show: my-show-rule.with()
+#my-func()
+```
+
+### Installation
+
+A step by step guide that will tell you how to get the development environment up and running. This should example how to clone the repo and where to (maybe a link to the typst documentation on it), along with any pre-requisite software and installation steps.
+
+```
+$ First step
+$ Another step
+$ Final step
+```
+
+## Usage
+
+A more in-depth description of usage. Any template arguments? A complicated example that showcases most if not all of the functions the package provides? This is also an excellent place to signpost the manual.
+
+```typ
+#import "@preview/my-package:0.1.0": *
+
+#let my-complicated-example = ...
+```
+
+## Additional Documentation and Acknowledgments
+
+* Project folder on server:
+* Confluence link:
+* Asana board:
+* etc...

scripts/package

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -eu
+
+# adapted from https://github.com/johannes-wolf/cetz/blob/35c0868378cea5ad323cc0d9c2f76de8ed9ba5bd/scripts/package
+# licensed under Apache License 2.0
+
+. "$(dirname "${BASH_SOURCE[0]}")/setup"
+
+if (( $# < 1 )) || [[ "${1:-}" == "help" ]]; then
+  echo "package TARGET"
+  echo ""
+  echo "Packages all relevant files into a directory named '<name>/<version>'"
+  echo "at TARGET. If TARGET is set to @local or @preview, the local Typst package"
+  echo "directory will be used so that the package gets installed for local use."
+  echo "The name and version are read from 'typst.toml' in the project root."
+  echo ""
+  echo "Local package prefix: $DATA_DIR/typst/package/local"
+  echo "Local preview package prefix: $DATA_DIR/typst/package/preview"
+  exit 1
+fi
+
+TARGET="$(resolve-target "${1:?Missing target path, @local or @preview}")"
+echo "Install dir: $TARGET"
+
+# ignore rules
+readarray -t ignores < <(grep -v '^#' .typstignore | grep '[^[:blank:]]')
+
+# recursively print all files that are not excluded via .typstignore
+function enumerate {
+	local root="$1"
+	if [[ -f "$root" ]]; then
+		echo "$root"
+	else
+		local files
+		readarray -t files < <(find "$root" \
+      -mindepth 1 -maxdepth 1 \
+      -not -name .git \
+      -not -name .typstignore)
+		# declare -p files >&2
+
+		local f
+		for f in "${files[@]}"; do
+			local include
+			include=1
+
+			local ignore
+			for ignore in "${ignores[@]}"; do
+				if [[ "$ignore" =~ ^! ]]; then
+					ignore="${ignore:1}"
+					if [[ "$f" == ./$ignore ]]; then
+						# echo "\"$f\" matched \"!$ignore\"" >&2
+						include=1
+					fi
+				elif [[ "$f" == ./$ignore ]]; then
+					# echo "\"$f\" matched \"$ignore\"" >&2
+					include=0
+				fi
+			done
+			if [[ "$include" == 1 ]]; then
+				enumerate "$f"
+			fi
+		done
+	fi
+}
+
+# List of all files that get packaged
+readarray -t files < <(enumerate ".")
+# declare -p files >&2
+
+TMP="$(mktemp -d)"
+
+for f in "${files[@]}"; do
+  mkdir -p "$TMP/$(dirname "$f")" 2>/dev/null
+  cp -r "$ROOT/$f" "$TMP/$f"
+done
+
+TARGET="${TARGET:?}/${PKG_PREFIX:?}/${VERSION:?}"
+echo "Packaged to: $TARGET"
+if rm -r "${TARGET:?}" 2>/dev/null; then
+  echo "Overwriting existing version."
+fi
+mkdir -p "$TARGET"
+
+# include hidden files by setting dotglob
+shopt -s dotglob
+mv "$TMP"/* "$TARGET"