Tweak docs (#5089)

4 files changed, 33 insertions, 42 deletions

diff --git a/docs/guides/guide-for-latex-users.md b/docs/guides/guide-for-latex-users.md
index 8500e18b..f8b2e439 100644
--- a/docs/guides/guide-for-latex-users.md
+++ b/docs/guides/guide-for-latex-users.md
@@ -25,6 +25,18 @@ In the following, we will cover some of the most common questions a user
 switching from LaTeX will have when composing a document in Typst. If you prefer
 a step-by-step introduction to Typst, check out our [tutorial].
 
+## Installation
+You have two ways to use Typst: In [our web app](https://typst.app/signup/) or
+by [installing the compiler](https://github.com/typst/typst/releases) on your
+computer. When you use the web app, we provide a batteries-included
+collaborative editor and run Typst in your browser, no installation required.
+
+If you choose to use Typst on your computer instead, you can download the
+compiler as a single, small binary which any user can run, no root privileges
+required. Unlike LaTeX, packages are downloaded  when you first use them and
+then cached locally, keeping your Typst installation lean. You can use your own
+editor and decide where to store your files with the local compiler.
+
 ## How do I create a new, empty document? { #getting-started }
 That's easy. You just create a new, empty text file (the file extension is
 `.typ`). No boilerplate is needed to get started. Simply start by writing your
@@ -452,10 +464,10 @@ and their corresponding Typst functions.
 | enumitem                        | [`list`], [`enum`], [`terms`] functions    |
 
 Although _many_ things are built-in, not everything can be. That's why Typst has
-a built-in [package manager]($universe) where the community can share their
-creations and automations. Let's take, for instance, the _cetz_ package: This
-package allows you to create complex drawings and plots. To use cetz in your
-document, you can just write:
+its own [package ecosystem]($universe) where the community share its creations
+and automations. Let's take, for instance, the _cetz_ package: This package
+allows you to create complex drawings and plots. To use cetz in your document,
+you can just write:
 
 ```typ
 #import "@preview/cetz:0.2.1"
@@ -464,15 +476,15 @@ document, you can just write:
 (The `@preview` is a _namespace_ that is used while the package manager is still
 in its early and experimental state. It will be replaced in the future.)
 
-Aside from the official package repository, you might also want to check out the
+Aside from the official package hub, you might also want to check out the
 [awesome-typst repository](https://github.com/qjcg/awesome-typst), which
 compiles a curated list of resources created for Typst.
 
 If you need to load functions and variables from another file within your
 project, for example to use a template, you can use the same
-[`{import}`]($scripting/#modules) statement with a file name rather than a
+[`import`]($scripting/#modules) statement with a file name rather than a
 package specification. To instead include the textual content of another file,
-you can use an [`{include}`]($scripting/#modules) statement. It will retrieve
+you can use an [`include`]($scripting/#modules) statement. It will retrieve
 the content of the specified file and put it in your document.
 
 ## How do I input maths? { #maths }
@@ -626,28 +638,15 @@ use in prose (cf. `\citet` and `\textcite`) are available with
 You can find more information on the documentation page of the [`bibliography`]
 function.
 
-## Installation
-You have two ways to use Typst: In [our web app](https://typst.app/signup/) or
-by [installing the compiler](https://github.com/typst/typst/releases) on your
-computer. When you use the web app, we provide a batteries-included
-collaborative editor and run Typst in your browser, no installation required.
-
-If you choose to use Typst on your computer instead, you can download the
-compiler as a single, small binary which any user can run, no root privileges
-required. Unlike LaTeX, packages are downloaded  when you first use them and
-then cached locally, keeping your Typst installation lean. You can use your own
-editor and decide where to store your files with the local compiler.
-
 ## What limitations does Typst currently have compared to LaTeX? { #limitations }
 Although Typst can be a LaTeX replacement for many today, there are still
 features that Typst does not (yet) support. Here is a list of them which, where
 applicable, contains possible workarounds.
 
-- **Native charts and plots.** LaTeX users often create charts along with their
-  documents in PGF/TikZ. Typst does not yet include tools to draw diagrams, but
-  the community is stepping up with solutions such as
-  [`cetz`](https://github.com/johannes-wolf/typst-canvas). You can add those
-  to your document to get started with drawing diagrams.
+- **Well-established plotting ecosystem.** LaTeX users often create elaborate
+  charts along with their documents in PGF/TikZ. The Typst ecosystem does not
+  yet offer the same breadth of available options, but the ecosystem around the
+  [`cetz`](https://github.com/cetz-package/cetz) package is catching up quickly.
 
 - **Change page margins without a pagebreak.** In LaTeX, margins can always be
   adjusted, even without a pagebreak. To change margins in Typst, you use the
@@ -661,12 +660,3 @@ applicable, contains possible workarounds.
   tools](https://cloudconvert.com/pdf-to-svg) or
   [Inkscape](https://inkscape.org/). The web app will automatically convert PDF
   files to SVG files upon uploading them.
-
-- **Page break optimization.** LaTeX runs some smart algorithms to not only
-  optimize line but also page breaks. While Typst tries to avoid widows and
-  orphans, it uses less sophisticated algorithms to determine page breaks. You
-  can insert custom page breaks in Typst using `[#pagebreak(weak: true)]` before
-  submitting your document. The argument `weak` ensures that no double page
-  break will be created if this spot would be a natural page break anyways. You
-  can also use `[#v(1fr)]` to distribute space on your page. It works quite
-  similar to LaTeX's `\vfill`.
diff --git a/docs/guides/page-setup.md b/docs/guides/page-setup.md
index 0c5bdf6d..6ae92f83 100644
--- a/docs/guides/page-setup.md
+++ b/docs/guides/page-setup.md
@@ -38,7 +38,7 @@ in your template.
   number-align: center,
 )
 
-#rect(fill: aqua)
+#rect(fill: aqua.lighten(40%))
 ```
 
 This example visualizes the dimensions for page content, headers, and footers.
diff --git a/docs/reference/context.md b/docs/reference/context.md
index 0ea88975..bdd520f5 100644
--- a/docs/reference/context.md
+++ b/docs/reference/context.md
@@ -59,12 +59,12 @@ context is known. The body of a context expression may be evaluated zero, one,
 or multiple times, depending on how many different places it is put into.
 
 ## Location context
-Context cannot only give us access to set rule values. It can also let us know
-_where_ in the document we currently are, relative to other elements, and
-absolutely on the pages. We can use this information to create very flexible
-interactions between different document parts. This underpins features like
-heading numbering, the table of contents, or page headers dependent on section
-headings.
+We've already seen that context gives us access to set rule values. But it can
+do more: It also lets us know _where_ in the document we currently are, relative
+to other elements, and absolutely on the pages. We can use this information to
+create very flexible interactions between different document parts. This
+underpins features like heading numbering, the table of contents, or page
+headers dependent on section headings.
 
 Some functions like [`counter.get`]($counter.get) implicitly access the current
 location. In the example below, we want to retrieve the value of the heading
diff --git a/docs/src/lib.rs b/docs/src/lib.rs
index 5670fa6f..4ee6d50d 100644
--- a/docs/src/lib.rs
+++ b/docs/src/lib.rs
@@ -249,14 +249,15 @@ fn category_page(resolver: &dyn Resolver, category: Category) -> PageModel {
 
     let mut skip = HashSet::new();
     if category == MATH {
-        // Already documented in the text category.
-        skip.insert("text");
         skip = GROUPS
             .iter()
             .filter(|g| g.category == category.name())
             .flat_map(|g| &g.filter)
             .map(|s| s.as_str())
             .collect();
+
+        // Already documented in the text category.
+        skip.insert("text");
     }
 
     // Add values and types.