Add template bundling and first templates (typst#394)

Co-authored-by: Laurenz <[email protected]>

.github/pull_request_template.md

@@ -25,3 +25,8 @@ I have read and followed the submission guidelines and, in particular, I
 - [ ] have chosen a license and added a `LICENSE` file or linked one in my `README.md`
 - [ ] tested my package locally on my system and it worked
 - [ ] `exclude`d PDFs or README images, if any, but not the LICENSE
+
+<!--
+The following box only needs to be checked for **template** submissions. If you're submitting a package that isn't a template, you can delete the following section. See the guidelines section about licenses in the README for more details.
+-->
+- [ ] ensured that my package is licensed such that users can use and distribute the contents of its template directory without restriction, after modifying them through normal use.

CATEGORIES.md

@@ -0,0 +1,59 @@
+# Typst Package Categories
+Categories help users explore packages, make finding the right one easier, and
+provide package authors with a reference for best-practices in similar packages.
+In addition to categories, packages can also specify a list of [disciplines]
+describing their target audience.
+
+Each package can declare itself a part of up to three categories.
+
+There are two kinds of package categories: Functional categories that describe
+what a package does on a technical level and publication categories that
+describe for which kind of deliverable a package may be used.
+
+Package authors are not required to pick a category from each of the two
+groups. Instead, they can omit one group completely if it is not applicable to
+their package, or use two categories for another group. Publication categories,
+for example, are of big relevance to template packages and less so to a general
+utility package that may apply to most publication kinds.
+
+## Functional Categories
+- **`components`:** Building blocks for documents. This includes boxes, layout
+  elements, marginals, icon packs, color palettes, and more.
+- **`visualization`:** Packages producing compelling visual representations of
+  data, information, and models.
+- **`model`:** Tools for managing semantic information and references. Examples
+  could be glossaries and bibliographic tools.
+- **`layout`:** Primitives and helpers to achieve advanced layouts and set up a
+  page with headers, margins, and multiple content flows.
+- **`text`:** Packages that transform text and strings or are focused on fonts.
+- **`languages`:** Tools for localization and internationalization as well as
+  dealing with different scripts and languages in the same document.
+- **`scripting`:** Packages/libraries focused on the programmatic aspect of
+  Typst, useful for automating documents.
+- **`integration`:** Integrations with third-party tools and formats. In
+  particular, this includes packages that embed a third-party binary as a
+  plugin.
+- **`utility`:** Auxiliary packages/tools, for example for creating
+  compatibility and authoring packages.
+- **`fun`:** Unique uses of Typst that are not necessarily practical, but
+  always entertaining.
+
+## Publication Categories
+- **`book`:** Long-form fiction and non-fiction books with multiple chapters.
+- **`report`:** A multipage informational or investigative document focused on
+  a single topic. This category contains templates for tech reports, homework,
+  proposals and more.
+- **`paper`:** A scientific treatment on a research question. Usually published
+  in a journal or conference proceedings.
+- **`thesis`:** A final long-form deliverable concluding an academic degree.
+- **`poster`:** A large-scale graphics-heavy presentation of a topic. A poster
+  is intended to give its reader a first overview over a topic at a glance.
+- **`flyer`:** Graphics-heavy, small leaflets intended for massive circulation
+  and to inform or convince.
+- **`presentation`:** Slides for a projected, oral presentation.
+- **`cv`:** A résumé or curriculum vitæ presenting the author's professional
+  achievements in a compelling manner.
+- **`office`:** Staples for the day-to-day in an office, such as a letter or an
+  invoice.
+
+[disciplines]: https://github.com/typst/packages/blob/main/DISCIPLINES.md

DISCIPLINES.md

@@ -0,0 +1,51 @@
+# Typst Package Disciplines
+Disciplines define the target audience of a package, making it easy for users to
+discover domain-specific packages and templates. Not all packages are
+domain-specific, those can simply omit the `disciplines` key from their
+manifest. In addition to disciplines, packages can also specify a list of
+[categories] describing their functionality.
+
+Disciplines are standardized for discoverability. If you want to submit a
+domain-specific package, but there isn't a fitting discipline in the list below,
+please reach out to us!
+
+The following disciplines are currently defined:
+
+- `agriculture`
+- `anthropology`
+- `archaeology`
+- `architecture`
+- `biology`
+- `business`
+- `chemistry`
+- `communication`
+- `computer-science`
+- `design`
+- `drawing`
+- `economics`
+- `education`
+- `engineering`
+- `fashion`
+- `film`
+- `geography`
+- `geology`
+- `history`
+- `journalism`
+- `law`
+- `linguistics`
+- `literature`
+- `mathematics`
+- `medicine`
+- `music`
+- `painting`
+- `philosophy`
+- `photography`
+- `physics`
+- `politics`
+- `psychology`
+- `sociology`
+- `theater`
+- `theology`
+- `transportation`
+
+[categories]: https://github.com/typst/packages/blob/main/CATEGORIES.md

README.md

@@ -13,7 +13,7 @@ name = "example"
 version = "0.1.0"
 entrypoint = "lib.typ"
 authors = ["The Typst Project Developers"]
-license = "Unlicense"
+license = "MIT"
 description = "An example package."
 ```
 
@@ -34,12 +34,17 @@ Required for submissions to this repository:
   grammar and spelling mistakes as it will appear in the [package list][list].
 
 Optional:
-- `homepage`: A link to the package's web presence where there could be more
+- `homepage`: A link to the package's web presence, where there could be more
   details, an issue tracker, or something else. Will be linked to from the
   package list.
 - `repository`: A link to the repository where this package is developed. Will
   be linked to from the package list if there is no homepage.
 - `keywords`: An array of search keywords for the package.
+- `categories`: An array with up to three categories from the
+  [list of categories][categories] to help users discover the package.
+- `disciplines`: An array of [disciplines] defining the target audience for
+  which the package is useful. Should be empty if the package is generally
+  applicable.
 - `compiler`: The minimum Typst compiler version required for this package to
   work.
 - `exclude`: An array of globs specifying files that should not be part of the
@@ -48,6 +53,60 @@ Optional:
   otherwise unnecessarily increase the bundle size. Don't exclude the README or
   the LICENSE.
 
+Packages always live in folders named as `{name}/{version}`. The name and
+version in the folder name and manifest must match. Paths in a package are local
+to that package. Absolute paths start in the package root, while relative paths
+are relative to the file they are used in.
+
+### Templates
+Packages can act as templates for user projects. In addition to the module that
+a regular package provides, a template package also contains a set of template
+files that Typst copies into the directory of a new project.
+
+In most cases, the template files should not include the styling code for the
+template. Instead, the template's entrypoint file should import a function from
+the package. Then, this function is used with a show rule to apply it to the
+rest of the document.
+
+Template packages (also informally called templates) must declare the
+`[template]` key in their `typst.toml` file. A template package's `typst.toml`
+could look like this:
+
+```toml
+[package]
+name = "charged-ieee"
+version = "0.1.0"
+entrypoint = "lib.typ"
+authors = ["Typst GmbH <https://typst.app>"]
+license = "MIT-0"
+description = "An IEEE-style paper template to publish at conferences and journals for Electrical Engineering, Computer Science, and Computer Engineering"
+
+[template]
+path = "template"
+entrypoint = "main.typ"
+thumbnail = "thumbnail.png"
+```
+
+Required by the compiler:
+- `path`: The directory within the package that contains the files that should
+  be copied into the user's new project directory.
+- `entrypoint`: A path _relative to the template's path_ that points to the file
+  serving as the compilation target. This file will become the previewed file in
+  the Typst web application.
+
+Required for submissions to this repository:
+- `thumbnail`: A path relative to the package's root that points to a PNG or
+  lossless WebP thumbnail for the template. The thumbnail must depict one of the
+  pages of the template **as initialized.** The longer edge of the image must be
+  at least 1080px in length. Its file size must not exceed 3MB. Exporting a PNG
+  at 250 DPI resolution is usually a good way to generate a thumbnail. You are
+  encouraged to use [oxipng] to reduce the thumbnail's file size. The thumbnail
+  will automatically be excluded from the package files and must not be
+  referenced anywhere in the package.
+
+Template packages must specify at least one category in `package.categories`.
+
+### Third-party metadata
 Third-party tools can add their own entry under the `[tool]` section to attach
 their Typst-specific configuration to the manifest.
 
@@ -59,11 +118,6 @@ their Typst-specific configuration to the manifest.
 foo = "bar"
 ```
 
-Packages always live in folders named as `{name}/{version}`. The name and
-version in the folder name and manifest must match. Paths in a package are local
-to that package. Absolute paths start in the package root while relative paths
-are relative to the file they are used in.
-
 ## Published packages
 This repository contains a collection of published packages. Due to its early
 and experimental nature, all packages in this repository are scoped in a
@@ -72,6 +126,10 @@ and experimental nature, all packages in this repository are scoped in a
 Typst as `#import "@preview/{name}:{version}"`. You must always specify the full
 package version.
 
+You can use template packages to create new Typst projects with the CLI with
+the `typst init` command or the web application by clicking the _Start from
+template_ button.
+
 ### Submission guidelines
 To submit a package, simply make a pull request with the package to this
 repository. There are a few requirements for getting a package published, which
@@ -85,28 +143,66 @@ are detailed below:
   is redundant). If they contain multiple words, names should use `kebab-case`.
   Look at existing packages and PRs to get a feel for what's allowed and what's
   not.
+
+  *Additional guidance for template packages:* It is often desirable for
+  template names to feature the name of the organization or publication the
+  template is intended for. However, it is still important to us to accommodate
+  multiple templates for the same purpose. Hence, template names shall consist
+  of a unique, non-descriptive part followed by a descriptive part. For example,
+  a template package for the fictitious _American Journal of Proceedings (AJP)_
+  could be called `organized-ajp` or `eternal-ajp`. Package names should be
+  short and use the official entity abbreviation. Template authors are
+  encouraged to add the full name of the affiliated entity as a keyword.
+
+  The unamended entity name (e.g. `ajp`) is reserved for official template
+  packages by their respective entities. Please make it clear in your PR if you
+  are submitting an official package. We will then outline steps to authenticate
+  you as a member of the affiliated organization.
+
+  If you are an author of an original template not affiliated with any
+  organization, only the standard package naming guidelines apply to you.
+
 - **Functionality:** Packages should conceivably be useful to other users and
   should expose their capabilities in a reasonable fashion.
+
 - **Documentation:** Packages must contain a `README.md` file documenting (at
   least briefly) what the package does and all definitions intended for usage by
   downstream users. Examples in the README should show how to use the package
   through an `@preview` import. If you have images in your README, you might
   want to check whether they also work in dark mode. Also consider running
   [`typos`][typos] through your package before release.
+
 - **Style:** No specific code style is mandated, but two spaces of indent and
   kebab-case for variable and function names are recommended.
+
 - **License:** Packages must be licensed under the terms of an
   [OSI-approved][OSI] license. In addition to specifying the license in the
   TOML manifest, a package must either contain a `LICENSE` file or link to one
   in its `README.md`.
+
+  *Additional details for template packages:* If you expect the package
+  license's provisions to apply to the contents of the template directory (used
+  to scaffold a project) after being modified through normal use, especially if
+  it still meets the _threshold of originality,_ you must ensure that users of
+  your template can use and distribute the modified contents without
+  restriction. In such cases, we recommend licensing at least the template
+  directory under a license that requires neither attribution nor distribution
+  of the license text. Such licenses include MIT-0 and Zero-Clause BSD. You can
+  use an SPDX AND expression to selectively apply different licenses to parts of
+  your package. In this case, the README or package files must make clear under
+  which license they fall. If you explain the license distinction in the README
+  file, you must not exclude it from the package.
+
 - **Size:** Packages should not contain large files or a large number of files.
   This will be judged on a case-by-case basis, but if it needs more than ten
   files, it should be well-motivated. To keep the package small and fast to
   download, please `exclude` images for the README or PDF files with
   documentation from the bundle. Alternatively, you can link to images hosted on
   a githubusercontent.com URL (just drag the image into an issue).
+
 - **Security:** Packages must not attempt to exploit the compiler or packaging
   implementation, in particular not to exfiltrate user data.
+
 - **Safety:** Names and package contents must be safe for work.
 
 This list may be extended over time as improvements/issues to the process are
@@ -121,20 +217,6 @@ There is one exception: Minor fixes to the documentation or TOML metadata of a
 package are allowed _if_ they can not affect the package in a way that might
 break downstream users.
 
-### Templates
-**Important:** Please do not submit templates as packages just yet. To make the
-experience of using templates as seamless as possible, we want them to show up
-in the web app's template gallery and we want the CLI to be able to scaffold a
-project from a template. We ask for your patience while we're
-[building][template-packages] the necessary infrastructure.
-
-What's the difference between a template and a normal package? The line isn't
-100% sharp, but overall a template will aid you in producing a full document
-with a particular style, whereas normal packages provide building blocks and
-automations useful across a range of documents. In particular, templates will
-often ship with one or more template files from which a new project can be
-scaffolded. This requires additional package metadata.
-
 ### Downloads
 The Typst compiler downloads packages from the `preview` namespace on-demand.
 Once used, they are cached in `{cache-dir}/typst/packages/preview` where
@@ -173,7 +255,9 @@ the Apache-2.0 license. Packages in `packages/` are licensed under their
 respective license.
 
 [list]: https://typst.app/docs/packages/
+[categories]: https://github.com/typst/packages/blob/main/CATEGORIES.md
+[disciplines]: https://github.com/typst/packages/blob/main/DISCIPLINES.md
 [SemVer]: https://semver.org/
 [OSI]: https://opensource.org/licenses/
-[template-packages]: https://github.com/typst/typst/issues/2432
 [typos]: https://github.com/crate-ci/typos
+[oxipng]: https://github.com/shssoichiro/oxipng