docs: improve docs for writing documentation and what files to exclude

Author: saecki

docs/documentation.md

@@ -6,16 +6,25 @@ Examples in the README should show how to use the package through a `@preview`
 import. Also consider running [`typos`][typos] through your package before
 release.
 
-More complete documentation (usually written in Markdown, or in a PDF
-generated from a Typst file) can be linked from this README.
+More complete documentation (usually written in Markdown, or in a PDF generated
+from a Typst file) can be linked from this README. In general there are two
+options for linking these resources:
+
+If the resources are committed to this repository, you should link them locally.
+For example like this: `[manual.pdf](docs/manual.pdf)`. Most of these files
+should be excluded in your [manifest], see [what to exclude].
+
+If the resources are stored elsewhere, you can link to their URL as usual. When
+linking to files from another git repository, consider linking to a specific tag
+or revision, instead of the `main` branch. This will ensure that the linked
+resources always match the version of the package. So for example, prefer linking
+to the first URL instead of the second one:
+1. `https://github.com/micheledusi/Deckz/blob/v0.3.0/docs/manual-deckz.pdf`
+2. `https://github.com/micheledusi/Deckz/blob/main/docs/manual-deckz.pdf`
 
 If your package has a dedicated documentation website, it can be linked in the
 README, but also via the `homepage` field of your [manifest].
 
-When linking to a manual, images, etc. from another git repository, consider
-linking to a specific tag or revision, instead of the `main` branch. This will
-ensure that the linked resources always match the version of the package.
-
 ## Differences from standard Markdown
 
 Typst Universe processes your package README before displaying it,
@@ -44,5 +53,6 @@ using the following snippet:
 
 [typos]: https://github.com/crate-ci/typos
 [manifest]: manifest.md
+[what to exclude]: tips.md#what-to-commit-what-to-exclude
 [alert blocks]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
 [emoji shortcodes]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#using-emojis

docs/manifest.md

@@ -66,10 +66,11 @@ Optional:
 - `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
-  published bundle that the compiler downloads when importing the package. To be
-  used for large support files like images or PDF documentation that would
+  published bundle that the compiler downloads when importing the package. These
+  files will still be available on typst universe to link to from the README.\
+  To be used for large support files like images or PDF documentation that would
   otherwise unnecessarily increase the bundle size. Don't exclude the README or
-  the LICENSE.
+  the LICENSE, see [what to exclude].
 
 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
@@ -219,4 +220,5 @@ foo = "bar"
 [SemVer]: https://semver.org/
 [oxipng]: https://github.com/shssoichiro/oxipng
 [license]: licensing.md
-[description]: #writing-a-good-description
+[description]: #writing-a-good-description
+[what to exclude]: tips.md#what-to-commit-what-to-exclude

docs/tips.md

@@ -37,29 +37,36 @@ larger than they need to be.
 
 There are two solutions to limit this problem: excluding files from the archive
 (using the `exclude` key in your [package manifest][manifest]), or simply not
-commiting the files to this repository in the first place.
+committing the files to this repository in the first place.
 
 To know which strategy to apply to each file, we can split them in three groups:
 
-- Files that are necessary for the package to work. If any of these files are
-  removed, the package would break for the end user. This includes the manifest
-  file, main Typst file and its dependencies, and in case of a template package,
-  any file in the template directory.
-- Files that are necessary for the package to be displayed correctly on Typst
-  Universe. This includes the README, and any files that are linked from there
-  (manuals, examples, illustrations, etc.). These files can easily be accessed
-  by opening the package README.
-- Other files. This generally includes test files, build scripts, but also
-  examples or manuals that are not linked in the README. These files would be
-  almost impossible to access for the final user, unless they browse this GitHub
-  repository or their local package cache.
-
-The first two groups should be commited to this repository, but files that are
-not strictly necessary for the package to work (the second group) should be
-excluded in `typst.toml`. The third group should simply not be copied here, or
-you should consider linking them from your README so that they are easily
-discoverable. A good example showing how to link examples and a manual is
-[CeTZ][cetz].
+__1. Required files__\
+Files that are necessary for the package to work. If any of these files are
+removed, the package would break for the end user. This includes the manifest
+file, main Typst file and its dependencies, and in case of a template package,
+any file in the template directory.
+
+__2. Documentation files__\
+Files that are necessary for the package to be displayed correctly on Typst
+Universe. This includes the README, and any files that are linked from there
+(manuals, examples, illustrations, etc.). These files can easily be accessed
+by opening the package README.
+
+__3. Other files__\
+This generally includes test files, build scripts, but also examples or manuals
+that are not linked in the README. These files would be almost impossible to
+access for the final user, unless they browse this GitHub repository or their
+local package cache.
+
+The first two groups (required and documentation files) should be committed to
+this repository. And files that are not strictly necessary for the package to
+work (documentation files) should be excluded in `typst.toml`. They will still
+be available on typst universe to link to from the README.\
+The third group should simply not be committed to this repository. If you think
+some of the remaining files are important, they probably belong to the second
+group and should be linked in the README, so that they are easily discoverable.
+A good example showing how to link examples and a manual is [CeTZ][cetz].
 
 The only exceptions to this rule are the LICENSE file (that should always be
 available along with the source code, so it should not be excluded), and the