01| Basic Markdown

Miles Robertson, 08.12.25

Introduction

One of Typst's great features is how easy it is to get started when learning. You can always learn more details about advanced features if you want to have more control over your documents, but you can just as easily have clean, well-organized documents right out of the box with very little editing.

Many places on the internet and elsewhere use "markdown", which is an easy way to write simple formatted text on computers. There are many different versions of markdown, but regardless of the version, it requires virtually no coding knowledge to get started. Typst uses its own "flavor" of markdown as the foundation of its syntax, which enables you to easily make documents with paragraphs, bulleted/numbered lists, bold/italicized text, and various sizes of headings. This is a great place to start learning Typst given how it is both fundamental and approachable.

To facilitate the many things that users might want out of a typesetting language, Typst has various "modes" that are used for different purposes. In this chapter, we are exclusively discussing "markdown mode". In this mode, you create content (i.e., text, images, etc. that are placed into your document) by typing text to be put on the screen, while using markdown notation where necessary.

In this section and throughout this tutorial, whenever there is relevant documentation in Typst's website, I will link to that page if you want to read further.

Setting Up Typst

Before getting into this chapter, I point you towards Typst's signup page to create a free account. Technically, you can do everything with Typst offline without getting an account, but it requires some setup that would complicate your first steps. Once you create an account, click on + Empty Document to get started with your first Typst document. Give it any name you like. Once open, the left-hand side of the screen is where you can type Typst code, and the right immediately shows it rendered to the screen.

At any point while creating a Typst document, you can click the download button on the top right corner of the screen. You can download your work as a .pdf, .png, or .svg.

Basic Text Styling

To start, I will introduce how to bold or italicize words. Type the following into your Typst document's code panel:

These are examples of _italicized text_ and *bolded text*.

As you can see, surrounding text with underscores _ italicizes the output, whereas using asterisks * causes it to be bolded. This is a really fast way to manage this simple formatting, as you can see exactly where styled text begins and ends. This can be much better than graphic interfaces like MS Word, where you can only see formatting through the text itself and thus might miss small details about where it begins or ends.

You can also bold and italicize words at once by combining these symbols, one pair of them surrounding the other:

Both _*this phrase*_ and *_this phrase_* are italicized and bolded.

Whitespaces

As discussed in the previous chapter, "whitespaces" are characters that you cannot see but often take up space, such as spaces or newlines (i.e., hitting the enter key). Since they are invisible, programs like MS Word make it difficult to edit them or know what they are. On the other hand, Typst makes whitespaces very easy to identify.

Spaces are pretty self-explanatory: a space in your Typst code is a space in your document. However, it is important to realize that multiple spaces in a row are truncated down to a single space. That means the following code will render showing just a single space between each word: There are no extra spaces in the output. This might feel limiting, but this can help give flexibility with how you organize your code (discussed more in later chapters).
Paragraph breaks are created with two new lines (e.g., hitting enter two times), so there is a full empty line between text. This means that one newline alone does not have any impact on the output, which can help give you some control over how you organize your Typst code.
Line breaks are similar to paragraph breaks, but do not form a new paragraph. Instead, it just leaves the rest of the line empty and continues on to the next line. They are inserted with a single backslash, \, and should be followed by a space or a new line. There is a difference in the spacing between lines and the spacing between paragraphs, and along with some other aspects this does make paragraph breaks and line breaks different. Usually, in normal typing, you will not use line breaks.

The code below summarizes these whitespaces (note that comments can be placed in Typst code, which are not rendered to the output, using two forward slashes, //):

It was the // new line here does not cause paragraph break
best of times,      it was the worst // extra spaces removed
of times, it was the age of wisdom, \ // slash makes line break
was the  \ age // slash within line also makes line break

of foolishness, // two new lines makes this new paragraph
it was the epoch of belief...

Bulleted and Numbered Lists

Very easily, you can make bulleted lists using dahses (-) while you can make numbered lists using either pluses (+) or numbers and periods (e.g., 1.). The example below demonstrates how you can use these, and even how they can be used with tabs to make sublists:

- this is one bullet point // note the newlines between items
- this is a second bullet point
- this is a third bullet point

+ this is the first numbered item
+ this is a second numbered item
+ this is a third numbered item
4. this is a fourth numbered item, explicitly set to be 4
7. this is another numbered item, except it is explicitly set to be 7

1. Monday
  - breakfast: pancakes
  - lunch: sandwich
  - dinner: salmon
2. Tuesday
  - breakfast: toast
  - lunch: salad
  - dinner: hamburger

Code Format

If you ever need to write a document that includes code, Typst (and other markdown languages) make this easy using backticks (``):

The variable `x` is multiplied by `2` and 
subtracted by `1` to get the new variable, `y_output`:

```python
y_output = 2 * x - 1
```

This can look like this in a `for` loop:

```python
x_list = range(100)
y_output_list = []
for x in x_list:
    y_output = 2 * x - 1
    y_output_list.append(y_output)
```

As you can see above, you can use backticks "in-line" (i.e., not on its own line), which will change the font to something friendlier for code. Additionally, triple-backticks can be used to style blocks of code. You can optionally add the specific language name immediately after the first three backticks, and this will add colors to some symbols like you might see in a code editor.

Headings

You can separate material in your documents easily by using headings. These are notated by using equals signs, =, as shown below. To take effect, the equals sign(s) needs to be at the beginning of the line, and must be followed by a space. The more equals signs, the lower level of header.

The code below also shows the first example of a function in Typst: lorem(). This function creates what is called "Lorem ipsum" text, which is simply nonsense filler words often used in typesetting to let you see how formatting looks before writing the actual content. Here, the number given to the function is the number of filler words the function returns (e.g., lorem(50) makes 50 filler words). If one wants to use a function in Typst, such as lorem(50), you have to indicate in some way that you want to use the function instead of literally wanting "lorem(50)" to appear in your output. Typst handles this by having you proceed the function with a pound symbol, like #lorem(50).

= Main Header

#lorem(30)  

== Sub-header

#lorem(35)  

=== Sub-sub-header

#lorem(20)

#lorem(35)

== Second Sub-header

#lorem(40)

Quick side note: since Typst has a special use for the pound sign, if you wanted to put a literal pound sign in your document, just precede it with a backslash: \#. This will "escape" the usual use for the pound sign, letting it be used in text.

Term Lists

As a quick note: you can quickly make lists of terms with the following syntax. It is great for things like definitions list, but is rare enough that I won't do more than show this example.

/ Obfuscate: To make something unclear or difficult 
    to understand.
/ Pernicious: Having a harmful effect, especially in a gradual 
    or subtle way.
/ Esoteric: Intended for or likely to be understood by only 
    a small number of people with specialized knowledge.
/ Ephemeral: Lasting for a very short time.
/ Inscrutable: Impossible to understand or interpret.

Conclusion

In this chapter, you learned the basics of Typst's markdown mode. We covered setting up your account, applying bold and italic styles, managing whitespaces, creating bulleted and numbered lists, using headings, and more. You also saw a basic function example with lorem(), and how # proceeds function names in markdown mode. These markdown skills are essential for creating documents in Typst. They allow you to produce organized content and form the basis for learning more advanced Typst features.

You can find a comprehensive list of things that can be done in markdown mode, including everything covered here and more, on this page. In the next chapter, you will learn how to further style markdown content to your specifications.

Practice

Replicate Document

Replicate the following in your own Typst document:

Here's a version of the same document that highlights the characteristics you should replicate:

The point of this is not to have to type it all out by hand, but instead to format existing text, so here is the raw text. Just click the text to select all of it at once.

North American Birds

A brief overview of some common birds found in North America
North America is home to a diverse range of bird species, 
from vibrant songbirds to majestic raptors. Whether you're a 
casual observer or an avid birdwatcher, learning about these 
birds can deepen your appreciation of the natural world.

Popular Species
American Robin (Turdus migratorius)
Northern Cardinal (Cardinalis cardinalis)
Blue Jay (Cyanocitta cristata)

Birdwatching Tips
Bring binoculars
Visit early morning or late afternoon

Continuing the list from above...
Learn bird calls
Use a field guide or app, like iNaturalist