How to Add Code Examples to Technical Documentation, and Why We Focus on Apple Platforms

Eline, originally from The Netherlands, is currently doing an English Language and Linguistics Master and is a member of The Soulmen’s support team. In her column, she responds to some of the most frequently asked questions and shares support answers that could be of interest for more Ulysses users out there.

Why Ulysses is Apple-Only

We keep getting a lot of requests to port Ulysses to various other operating systems, such as Microsoft Windows and Android:

@ulyssesapp Any plans for a release to Android or Windows?

— Mr Andersson (@rollspelosofen) March 25, 2016

We’re flattered by the requests to see Ulysses on other platforms. There are no plans to port Ulysses either to Microsoft Windows or to Android though. First, we’re true Apple enthusiasts. We have been using Apple devices in our professional and private lives for many years. We know these platforms well and would like to keep our focus on them. Second, both Microsoft Windows and Android greatly differ from Apple in their technical specifications, which means bringing Ulysses to them would be quite a lot of work for our small team. Nevertheless, thanks for asking.

Writing Technical Documentation in Ulysses

Ulysses is used by different kinds of writers. For example, writers who explain others how to build websites. They are often required to include examples of code. Here’s how you can do this with Ulysses.

Using Code Tags

When explaining how to build a website or app, you ideally want your examples to be clear and recognizable. Ulysses offers two different code tags for this purpose.

First, you can use the in-line code tags within a running sentence: write a single backtick `, then add the respective code and close the code example with another backtick. When you want to include a larger code snippet, you can use code block tags by writing two ticks ''. Then, add the code example and press ⏎ (return) twice to end the code block.

Code tags in Ulysses’ editor and when exported to HTML

The example above shows how this is done in the Editor, and what it looks like when exporting to HTML.

Fenced Code Blocks

Those who write technical documentation often do so in GitHub-Flavored Markdown (GFM), which uses a different way to add code snippets. These so-called fenced code blocks allow writers to add code by first writing triple back-ticks ```, followed by the example code, then closing the snippet again by adding another three back-ticks.

Ulysses doesn’t recognize fenced code blocks yet, but we might add native support for them in a future version.

Until that time, you can still add them by using a workaround: just pack your fenced code blocks in raw source block tags. You can do this by writing ~~ (double tildes), then add the fenced code block – Ulysses will automatically extend the raw source block around it.

Fenced code blocks in Ulysses’ editor and when exported to Markdown

As a last step, export your sheet as a Markdown file and you’ll be presented with a properly formatted GFM snippet, ready for use wherever you need it.

Do you have a question about Ulysses yourself? Please don’t hesitate to get in touch via our Contact Form. Eline and her colleagues from the Ulysses support will do their best to help you out.