Ulysses Style Reference

• Primary Source Redirect

• Archive

• Consolidated WTF - https://davidblue.wtf/ulysses/style

Defining Styles

With Ulysses Style Sheets you are able to create custom rich text styles for exporting your Ulysses documents. In order to assign a style to a certain definition in Ulysses, you just write a so-called style class. A style class consists of a style selector and some style settings:

xxxxxxxxxx
inline-strong {
font-family: "Cochin"
font-weight: bold
}

Style settings are written as key-value pairs, like font-family: "Cochin". A style setting ends on a line break. To place multiple settings in a line a semicolon ';' can be also used:

xxxxxxxxxx
inline-strong { font-family: "Cochin"; font-weight: bold; }

Ulysses style sheets provide you a many flexible way to re-use style settings through variables and expressions. We give a more detailed overview on style settings later. You will find an overview on all style settings in the Settings Reference.

Style Selectors

A style selector specifies when a style should be applied. The most simple style selector is a definition selector, like inline-strong or heading-1. However, if you want to create a style for an entire class of definitions, you may also use definition class selector, like list-all. These selectors match any contents of a certain type: For example the selector list-all matches all lists: e.g. list-ordered and list-unordered.

Besides the definitions used in your Ulysses document, there are also some general class selectors that describe settings regarding the visual appearance of the entire exported document. For example, the selector area-header and area-footer can be used to style of the header or footer area of any page in your document. The class document-settings contains general settings of the document, like the paper format. The setting defaults describe the base style for any node inside your document.

You will find a comprehensive overview of all possible definitions and their settings in the Class Reference.

Relative Selectors

Style selectors can be used in a very flexible way: with a relative style selector, you can specify that a style should be only used for content placed in a special position relative to other content. For example you can declare a style that should be only used for paragraphs following a heading1 in your document:

xxxxxxxxxx
heading-1 + paragraph {
margin-top: 0pt
}

The following relations can be used for relative style selectors:

Pseudoclasses

Further refinements on a style selector can be done with pseudoclasses. Some pseudoclasses may be used to determine the position of a node inside its parent node. For example, by using the :first pseudoclass you can specify that a certain style may be only applied to the first paragraph of a block quote:

xxxxxxxxxx
block-quote > paragraph :first {
   first-line-indent:0pt
}

It is also possible to specify multiple pseudoclasses at once:

xxxxxxxxxx
block-quote > paragraph :first :last {
   first-line-indent:0pt
}

There are also pseudoclasses that match depending on the position on the generated output. For example, the pseudoclasses :left-page, :right-page can be used to specify the format of a header or footer when exporting the left or right pages of a two-sided document. Finally, there are pseudoclasses used to specify a certain aspect of a style. For example the :enumerator pseudoclass is used to style the enumerator of an ordered list (e.g. to make a bullet point bold).

Currently, the following pseudoclasses exist:

Evaluation Order

In some cases multiple styles may match your content like the following example shows:

xxxxxxxxxx
list-all {
margin-top:5pt
margin-left:10pt
}

list-ordered {
margin-left:20pt
}

defaults {
font-size:14pt
}

In this case, styles are applied in the order of their occurrence. For example, if a node of the type list-ordered should be styled first list-all will be applied, then list-ordered and finally defaults. Thus, the computed style will be:

xxxxxxxxxx
margin-top:5pt// from list-all
margin-left:20pt// from list-ordered
font-size:14pt// from defaults

Inheritance

If you are exporting nodes that are nested in other nodes, the nested contents inherits all styles of higher level that it does not define by itself. Consider, you have the following Markdown document and the following Ulysses Style Sheet:

xxxxxxxxxx
> # Heading with **strong text**
> Normal text inside quote

block-quote {
font-family:"Cochin"
font-slant:italic
}

heading-1 {
font-family:"Futura"
font-size:24pt
}

inline-strong {
font-weight:bold
}

The style of “strong text” will be derived by mixing the style of block-quote with heading-1 and inline-strong. Whereas the settings of inner elements overwrite the settings of outer elements. Thus, the computed style will be:

xxxxxxxxxx
font-family:"Futura"// heading-1 overwrites the font-family of block-quote
font-slant:italic// Inherited form block-quote
font-size:24pt// Set by heading-1
font-weight:bold// Set by inline-strong

Mixins

Sometimes it is useful to create general presets that can be shared around multiple styles. For example the style inline-code and code-block may share the same font settings. This can be done by using mixins. A mixin is a set of predefined settings that can be embedded into other styles. The following example shows how a mixin @general-code-style is defined and how it is embedded to a style:

xxxxxxxxxx
@general-code-style {
font-family: "Courier"
font-size:   12pt
}

inline-code : @general-code-style {
     font-color: #0000ff
}

block-code : @general-code-style {
      font-color: #ffffff
      background-color: #0000ff
}

A mixin identifier always starts with an “@” character. A mixin identifier may contain any alphanumeric character. Multiple words are typically separated by dashes: @my-mixin-name. It is applied to a style definition after the style selector using a colon “:”. To apply multiple mixins to a style, just use a comma separated list:

xxxxxxxxxx
some-style : @first-mixin, @second-mixin, @third-mixin {
}

Using Style Settings

Any style consists of style settings describing all the visual details used for exporting a document. Typically, style settings consists of simple values - like assigning a setting font-weight the value bold

xxxxxxxxxx
inline-strong {
  font-weight: bold;
}

Types

Every style setting has a type that defines the valid values you may use for it. The type of each settings is documented in the Settings Reference. Currently, the following types exists:

Expressions

Ulysses Style Sheets allow you to use more complex expressions, employing arithmetic operators (+, -, *, /) and even variables containing present values. In the following example a variable $base-size is defined that is used as base value for styling heading1 and heading2.

xxxxxxxxxx
$base-size = 12pt

heading-1 {
     font-size: $base-size * 2
}

heading-2 {
font-size: $base-size * 0.5
}

Variables

Variable names begin with a dollar sign “$“ and consists of any alphanumeric characters and dashes. They are declared by assignment statements using the form $variable-name = VALUE. Whereas variable values may contain arbitrary expressions and variables themselves. For example, you may create a variable $heading-size that is calculated from the value of $base-size:

xxxxxxxxxx
$base-size = 12pt
$heading-size = $base-size * 2

Operators

In general, any expression may contain arithmetic operators (+, -, *, /) that combine values and variables. To group expressions it is possible to use round brackets:

xxxxxxxxxx
$some-variable = 4 * (5 / (2 + 3))

However, not every type supports any kind of operator. The following table shows you all possible combinations:

Class Reference

This section describes all available classes that can be used to style the export of an Ulysses document. We distinguish between two major types of style classes: General classes and Definition classes.

General Classes

General classes are all style classes used to define the visual appearance of the entire exported document (e.g. document-settings or header). Currently, the following general classes can be used:

Definition Classes

Definition classes are all style classes that can be used to style content with a concrete definition in your Ulysses document (e.g. strong or headline). You may currently use the following definition classes:

Settings Reference

This section gives you a detailed reference on any available style settings.

Overview

Document Settings

Headers and Footers

Footnotes Area

Inline

Media

Footnotes

Paragraph

Divider

List

Table

Table Cell

Editor Plugins

To support you editing ULSS styles, we’ve created plugins for TextMate 2 and Sublime Text 2. You may download and freely use them!

TextMate 2

TextMate 2 is a free text editor for OS X. To add support for ULSS syntax highlighting, follow these steps:

1. Download the plugin and extract it

2. Double-click the bundle file to install it

3. Restart TextMate 2

TextMate will now open .ulss files with our syntax highlighting and provide a (limited) auto-completion.

Sublime Text

With Sublime, you will get full syntax highlighting. The plugin is available on package control.

BBEdit and TextWrangler

We’ve also created a simple syntax highlighting plugin for BBEdit and TextWrangler. You may install it by the following steps:

1. Download the plugin and extract it

2. In Finder select the menu Go > Go to Folder and enter the following path:

   • BBEdit: ~/Library/Application Support/BBEdit/Language Modules

   • TextWrangler: ~/Library/Application Support/TextWrangler/Language Modules

3. Copy the file ULSS.plist inside this folder

4. Restart BBEdit / TextWrangler

Visual Studio Code

The Visual Studio Code package offers syntax highlighting and simple support for auto-completion. To install the plugin, follow these steps:

1. Visit the package’s marketplace site (don’t worry, it’s free).

2. Click install.

For more information on installing packages in Visual Studio Code, visit the getting stared guide.