Ulysses Style Sheets for novices

With Ulysses Style Sheets you can create custom styles for exporting PDF and RTF files. Your style settings are stored in a simple, but flexible text file format. It is loosely based on other style sheet formats like CSS. This tutorial will explain Ulysses Style Sheets step-by-step and without requiring any knowledge of other style sheet languages.

The single prerequisite for this tutorial is a text editor. To get auto-completion and colorful syntax highlighting, we suggest using either TextMate 2 or Sublime Text 2. We’ve created also a plugin for simple syntax highlighting in BBEdit and TextWrangler. For both applications, we provide plugins for ULSS.

Let’s start

You start by modifying a copy of a built-in style in Ulysses. This way you can use this style as a simple scaffold and don’t need to start from scratch. Just open “Preferences” from the Ulysses menu and select the “Styles” section. Double-click the “Novel Cochin” style and duplicate it. After that, double-click the copied style again and click “Edit” to open it with your favorite text editor.

After opening the style sheet in your text editor, you’ll see a text file containing a description of your export style. This text file is separated in many different sections. Every section is similar to the following example:

heading-all {
    font-family:    "Futura"
    …
}

If you scroll through the file you’ll see that there is a section for almost any definitions in Ulysses’ markups. For example, the section heading-all describes the generic styling of your headings. Another section inline-strong contains the styling of text using the strong markup. We call such a section style class.

At the beginning of each style class is a style selector (like heading-all or inline-strong). It tells Ulysses when a style class should be actually used. The selector is followed by a “block” surrounded with curly braces { }. This block contains the actual style settings as pairs of setting names and values. The example above specifies that all headings should use the font “Futura”.

So – let’s play. Change the font family of heading-all in your style sheet from “Futura” to “Avenir Next”:

heading-all {
    font-family:    "Avenir Next"
    …
    }

Save this change in your editor and switch back to Ulysses. Then create a simple sheet (with Markdown syntax) that contains the following lines:

# This is a **heading 1**!
## This is a **heading 2**!
This is a normal **paragraph**!

Export this sheet to PDF using your modified style. As you will see, all headings are now styled with the font ”Avenir Next”.

Don’t repeat yourself!

When creating style, you do not need to repeat yourself over and over again: instead of setting each font family or size for each markup definition, Ulysses automatically selects the right default values for each style. This way, you can change settings consistently at a single point without losing track of your design. If you look inside your style sheet you will see that all headings share the same font setting but use different font sizes:

heading-all {
    font-family:    "Zapfino"
    …
}

heading-1 {
    font-size:      33pt
    …
}

heading-2 {
    font-size:      22pt
    …
}

When styling text, Ulysses scans all your style classes from top to bottom. Whenever a style class matches your content, it will be used for styling it. For instance, for styling text inside a heading 2, the classes heading-all and heading-2 may match. Depending on their ordering in your style sheet ulysses will mix them. In our example, it will mix the font-family of heading-all with the font-size of heading-1 or heading-2. If two styles contain the same settings, the settings of the later style will be used.

Cascading Styles

Just recall our example text again:

## This is a **heading 2**!
This is a normal **paragraph**!

Besides a heading markup, it also contains some content marked up as “strong”. In one case, this strong text is part of a heading, while in the other case it is just inside an ordinary paragraph. In your export result, you see that this strong text is styled with a bold font. This font is automatically adapted to each paragraph style. Again, you don’t need to create separate styles for every single case. A single style for strong text is sufficient:

inline-strong {
    font-weight: bold
}

Whenever a markup is nested inside other markup, Ulysses automatically mixes their styles during export: the concrete style is composed by adding the styles of inner markups (e.g. inline-strong) to the styles of outer markups (e.g. heading-2). This way, you don’t have to create all possible style combinations.

Conditional Styles

However, in some cases you would like to style your text depending on its position. Imagine you don’t like to export any bold text inside a heading. How do you prevent styles from being mixed? The solution is to use conditional selectors. Just add another class in front of your inline-strong class:

heading-all inline-strong {
    font-weight: none
}

The style selector of this class must be read from right to left. It just means: “A strong text inside any kind of heading”. The settings of this style class state that such strong text should not be styled as bold. Since this style class is placed after the occurrence of inline-strong (inside the style sheet), it will override it.

Of course, there are other scenarios for conditional styles. For example, you may like to vary the first line indentation of a paragraph, depending whether it is the first paragraph after a heading or not. Again you can create a conditional style using the “+” relation:

paragraph {
    first-line-indent:  10pt
}

heading-all + paragraph {
    first-line-indent:  0pt
}

The first style class causes any paragraph to be styled with a first line indent of 10 points (pt). The second class overrides this setting for all paragraphs that immediately follow a heading.

There are much more possibilities to conditionally style your content; you can find a full overview on style selectors in the syntax overview.

How to continue?

So far, you just changed the style of some headings. Reading through the style sheet, you will find many more style classes. Many of them are similar to the definition names in your Ulysses markup: e.g. inline-emphasis styles emphasis text, block-code styles code blocks and list-ordered your ordered lists.

However, there are also some special style classes: the class defaults is used as base style for all text inside your document. If you change it, all unstyled text will change as well. The style class document-settings contains details applying to the entire exported document, like the paper format or the way footnotes are enumerated.

To learn more about all existing style classes and their style settings, you may use our comprehensive reference. To dig deeper in some more advanced features of ULSS, we strongly recommend our syntax overview. Furthermore, we’ve created some How-To’s explaining common tasks with Ulysses Style Sheets.