I'm really fed up with this damn document

[yourouchour]

The current documentation lacks the necessary descriptions such as show, set, function, etc. Some of the considerations for defining a function, such as not being able to modify global variables, are not mentioned at all. :( The documentation needs to get better.

[SillyFreak]

I feel your frustration; we’re aware that the documentation needs improvement. See e.g. here:

Could we have more examples (including straightforward ones) in the documentation?

It’s a fact that the current documentation is not great for beginners and we’re aware of it. We want to put greater focus on creating better introductory-level material in the near-ish future. We’ve noticed that some people love the docs and some don’t like them at all and the distinction is typically whether they are experienced programmers or not. That’s something we need to improve on: In part with tweaks to the reference, but primarily with better tutorial and guide-style documentation.

there are probably some other responses in that thread you may be interested in, in case you want some more context of the existing discussion.

Re the “in the near-ish future” in the post I linked: the plan is to migrate the docs themselves to Typst, which requires some more work on Typst’s HTML export. Once these two steps are finished, I’m fairly confident that doc improvements will come more into focus, maybe/hopefully also in terms of community contributions.

---

Re your concrete criticisms:

@yourouchour

lacks the necessary descriptions such as show, set

I assume you have seen Formatting – Typst Documentation; do you see any specific things missing from it? I’ll add a first thing: the only show rule there is for text, which is not even recommended most of the time (this is addressed on the next page of the tutorial though), and there’s no show-set example, even though that’s super important in practice.

@yourouchour

function, etc. Some of the considerations for defining a function, such as not being able to modify global variables, are not mentioned at all. :(

Functions in general are at Scripting – Typst Documentation, but yes, a detailed description what modifying a variable in Typst can and can’t achieve is necessary.

---

fwiw, the shortcomings mentioned in the previous thread were as a consequence reported on Github and promptly improved, so if you have concrete suggestions, please bring them. And if you have concrete questions, please ask them here on the forum.

[rfarhaz]

I also have a similar issue in the formatting section and in the text function that there should be an explicit example of how to use custom fonts locally. It is missing. There is a statement but I think an example would do justice.

[LRoInT]

Some functions should can be found easily, like symbol function. First time I read the big Symbol. Beacuse it is more easilier to found but it doesn’t have any information about symbol function. You can say it is a problem about my ability, but change it’s site can be better.

[maucejo]

I have the opposite feeling. I find the doc well written, although it could be improved (e.g. query section). I found many answers in the descriptions of the functions (such as the font argument of the text function).

For people coming from LaTeX or having some knowledge in programming language, Typst is quite easy to use.

An efficient way to learn Typst is to read the source code of Typst packages. I have learned a lot by doing this.

Don’t let your frustration to stop you using Typst

[Sergio]

I feel I’m a counterexample on the programmer/non-programmer divide.

I am an ocasional programmer with experience in a bunch of languages and even more experience in reading and parsing tech documentation, and I still have my gripes with parts of the docs.

Don’t get me wrong: I love that it is very systematic and easier to skim than LaTeX’s. But the two points I sometimes struggle with are:

• Examples. Some parameters take very specific values (e.g. strings that expect a specific format) and it sometimes takes too many links and a bit of guesswork to figure out how things are supposed to work. I find that happens most often to me with complex APIs like cetz, but also happened to mr recently while trying to understand the format of a function for filter. Many more examples for table configs (or a sort of formatting assistant for it) wouldn’t hurt either.
• It is sometimes tricky to find the right docs when you know what you want but not how Typst calls it. I seem to remember I struggled recently figuring how to draw an arc (part of a circle) because I wasn’t searching for the right word.

But this is just anecdotical. As usual, the groundwork is already amazing!

[jdpieck]

Building off of what @Sergio said, I really think there should be a dedicated “Examples” section in the documentation. I’m aware there are already examples within many of the function descriptions, but I would like to see a entire collection of examples for common use cases.

I believe that examples are a great way to introduce Typst concepts in a more nonlinear way. This could be exceptionally helpful for people just trying to get familiar with the Typst syntax, or people who just prefer to learn from following others.

I think this also has the potential to also address common formatting challenges and how others in the community have approached them. Speaking from personal experience, I did the vast majority of learning from looking at templates, the examples from the “Tutorial” section, and the overview example in the Typst Repo README.md.

[maucejo]

I think that About - Typst Examples Book fills some of your requirements.

[nleanba]

For me, the thing that is missing from the documentation is explicit documentation about show, show-set, show-if, and set rules. The section in the tutorial is not helpful when trying to get a quick reference.

I want a reference on these language features, with a quick overview over the syntax forms (it took me forever to figure out that conditional rules (set if) rules even exist) and a complete list of “element” functions – i.e. what is set/show-able and what is locate-able.

(Maybe it would help if Styling – Typst Documentation was labelled “set and show rules” instead of the vague “styling”)

In general though, I think the individual documentation entries are quite good, maybe my issue is with finding the correct one? It took me a while to get an intuition for how stuff is classified as “foundations”, “model”, “layout” and “visualize”. For example, I would expect Ratio Type – Typst Documentation and Float Type – Typst Documentation to be near each other (both are numerical types).

(sorry, this is a bit rambly)

[Mr.Selfridge]

I also miss reference pages for each and all Typst keywords. And proper well specified types for all parameters of all Typst functions.

Now they are severely lacking or I’m just blind. It is stated that some parameter has the type dictionary but not stated what kind of dictionary the parameter should be.

For example, many inset parameters can either a relative or a dictionary. And the example might show only inset: 5pt so it is very hard to guess what the dictionary should look like. Well I now know it takes properties like left or top but it should be documented. On some functions the dictionaries are documented but on some they are not.

I hope Typst gets a proper documentation some day but I understand it is not the main focus when the API is still changing a lot.

[Y.D.X]

@LRoInT

Some functions should can be found easily, like symbol function. First time I read the big Symbol. Beacuse it is more easilier to found but it doesn’t have any information about symbol function. You can say it is a problem about my ability, but change it’s site can be better.

+1, I’ve been using symbols for a long time, but I only learned that I can use symbol(…) a few days ago. I am adding the missing link in Miscellaneous minor doc improvements by YDX-2147483647 · Pull Request #6651 · typst/typst · GitHub. Hope it will help people in the next release cycle.

[jdpieck]

@maucejo

I think that About - Typst Examples Book fills some of your requirements.

This is really cool! Thanks for sharing this with me!

Some things that I would like to see more of (both in the official Typst documentation and in this resource in general) are examples structured around common use cases rather than specific Typst feature sets. In my opinion, we want to minimize the time the user spending trying to find specific functions to accomplish a specific output, rather than having to first go discover what functionality Typst actually has.

@nleanba

(it took me forever to figure out that conditional rules (set if) rules even exist)

Wait, I didn’t even know that set if is a thing…

@nleanba

I want a reference on these language features, with a quick overview over the syntax forms

I second this. Learning these fundamentals took way to long for me since I didn’t understand how to use them.

[sitandr]

Hey, author of the Examples Book here!

Can you please give some examples or specify what do you mean? How could it look?

@jdpieck

common use cases rather than specific Typst feature sets.

In general, I’m very open to any suggestions, though can’t spend as much time on the book as I want. Would be glad to hear any thoughts on that.

[jdpieck]

Pleasure meeting you @sitandr! I think you have already done a great job of providing a thorough alternative to the official documentation, and I have already learned a couple of new things :)

I’ve had to take some time to figure out how to best answer your question, and I believe that my thoughts primarily concern example categorization and organization. Reasonably so, you’ve opted to structure your book primarily around concepts, starting from the tools and then demonstrating their outputs, which mirrors the approach of the official documentation.

My main thought is that I would be interested in seeing some content organized by the desired output. For instance, instead of a section titled ‘Tables’ showing how to use the table tool, a user looking to create a ‘times table’ would first identify that specific output and then learn that the ‘table’ function is the tool to achieve it.

In other words, I don’t think there’s necessarily a scarcity of examples, but rather that when I’m trying to make something, I don’t typically start with the tools; I start with the desired end result.

I would be curious to hear your thoughts on this

(P.S. This output-first approach could also be supported by a small layout change: you may consider changing the example layout so we can see the output first instead of the source. This way, users immediately understand what the code snippet is working towards, before diving into the implementation details.)

[sitandr]

@jdpieck, thank you for the feedback!

In the case of “times table” I’m not sure it is okay to be a whole visible chapter. If there is a specific labelled example, the book search will most likely give it out immediately.

(well, in case of multiplication table the example wasn’t labelled, but I will fix it)

I’ve tried to split the book into two major parts: an extended tutorial part (Typst Basics) that covers all major concepts user really needs to know to master Typst, and Typst Snippets part. The latter tries to categorise examples roughly by the thing they try to accomplish. Sometimes only the headings are descriptive enough, so the examples would be accessible from search. Categorising them better isn’t easy, I’m afraid.

I really like your idea of moving the preview up, before the text. That’s not appliable everywhere, unfortunately. In the tutorial, for examples, it is important that person first sees the example, then the output.

I would like to make it configurable. Maybe I should try also using side-by-side view when possible, for better content-code correspondence.

The final note: I hope one day to migrate Typst Book to pure Typst with html export. That will (I hope) make it much easier to contribute and verify results with instant preview and other nice things. But that would certainly require big effort.

[Y.D.X]

@nleanba

For example, I would expect Ratio Type – Typst Documentation and Float Type – Typst Documentation to be near each other (both are numerical types).

Good news: Andrew improved the docs of ratio in January in Improved ratio and relative length docs by Andrew15-5 · Pull Request #5750 · typst/typst · GitHub. Now the page of ratio includes a table with links to related types. It will appear on Typst Documentation after the next release.

---

Besides, the Documentation forge on Discord has been created a few days ago.
If you find any tiny docs problem (so tiny that it’s not worth a dedicated issue or post), or want to join in improving the document, you can chat on that channel.
(Improving docs is really easy. No need to know rust.)