Web Export

The Web Export allows you to export Projects to a wide range of Web formats, such as XHTML, WordPress or Markdown.

Table of Contents:
  1. Concepts
  2. User Interface
  3. Default Templates
    1. Modern
    2. Minimal
    3. Snippets: Markdown, WordPress, XHTML
  4. Style Actions
    1. Paragraph Style Actions
    2. Inline Style Actions
    3. Reference Style Actions
    4. Marker Actions
  5. Creating Custom Templates
    1. The Template Manager
    2. The Template Editor
    3. Placeholders
    4. Actions
    5. Validation
    6. Post-Processing

Concepts

The design of this Exporter is based on the concept of Templates. With these Templates you can control the look and the structure of the exported files. For instance, one template could export the project into a website, which has a navigation bar on the left and displays the individual Documents on the right. Another template could display all exported Documents in one file. A third Template could export Documents to plain text files, which simply contain the content of the Document with WordPress markup.

Each Template comes with a set of Parameters, which allow you to customize the structure and the content of the exported Documents. Maybe you want to add Headers and Footers or want to set a Copyright text. Depending on your settings, the Exporter then enables or disables these sections or inserts text at pre-defined locations.

Like the other Exporters, you can assign a Style Action for each Paragraph Style, Inline Style or Marker. For instance, you could assign the Paragraph Style “Level 1” to a Heading action.

Ulysses includes five default Templates, which should work just great for most of your Projects. You can also create and customize your own Templates to adjust the exported files to your own needs. The following sections give a comprehensive overview of the features of the Web Export and how to harness them to create your own Templates.

User Interface

While the Web Export has a user interface similar to the other Exporters, some parts of the interface are different to accommodate sections for Templates and Parameters.

The top-most section is the Template selection. The popup button contains a list of Templates. The list is split into default Templates and custom Templates. Default Templates are the ones that come with Ulysses. They can neither be deleted nor edited. Custom Templates can be created, edited and deleted. Below the popup button, a brief description and the author are displayed. A preview picture of the Template is displayed on the right.

The second section holds a list of available Parameters for the currently selected Template. The names of these Parameters are displayed on the left. If no Parameters are available for the Template, this section is omitted.

Below you can find the Style Action selection. Just like in the other Exporters, all Paragraph Styles, Inline Styles and Markers are shown and you can set the Action for each Style or Marker. You can also select “Enclose in” as a Marker Action and enter characters that should enclose the marked text in the last column. To find out the markup of a specific Style or Marker, click on the button Show available Actions…, which is located at the top-right corner of the Style Action section.

The final section, Characters, is quite similar to the other Exporters. Here you can convert and correct certain characters such as double dashes or quotation marks.

Default Templates

The Web Export includes a selection of default Templates, which are explained below.

Modern Template

Modern

This Template is the most comprehensive one and contains a wide range of Style Actions. It features a navigation bar on the left containing a list of all exported Documents. The content of each Document is displayed on the right. This Template is especially suited for exports with a large number of Documents. Its Style Actions are the most important block and inline elements of the XHTML 1.1 specification.

The following Parameters allow for further customization:

Minmal Template

Minimal

Minimal takes a quite simplistic approach to exporting and puts all exported Documents in one file, separating them by a horizontal line. The Style Actions are identical to the Modern Template.

The Parameters are also basically the same as in Modern, except that there are no Header, Footer, and Background Parameters. However, the table of contents at the top of the XHTML file can be disabled using the Parameter of the same name.

Snippets: Markdown, WordPress, XHTML

The main purpose of these Templates is to allow simple export of text snippets to blogging engines and Content Management Systems such as WordPress or TYPO3. Every exported file contains only the text of a Document including the markup. No CSS files, No Metatags, etc.. The WebExport contains three snippet Templates: XHTML (largely identical to Modern), Markdown, and WordPress. Each of these Template has no Parameters.

Style Actions

Each Templates includes Style Actions for Paragraph Styles, Inline Styles, and Markers. In most cases, the code markup of the Action will enclose a paragraph or text range of an Inline Style or Marker. A special kind of Inline Styles, called Reference Styles, allow for more complex structures. In addition to these Style Actions, the Web Export offers default Actions, which will explained below as well.

You can always look up all Style Actions of the current Template by clicking on the Show available Actions… button.

Paragraph Style Actions

Most Paragraph Style Actions simply enclose the whole Paragraph in the markup. For instance, when using the Style Action Blockquote, the paragraph is enclosed in <blockquote> and </blockquote>.

However, some Actions not only enclose the paragraph, but also enclose a whole group of paragraphs with markup. This is especially useful for lists. For instance, if you apply the “List (Unordered)” Style Action of the Modern Template , each paragraph with this Action is enclosed with <li> and </li>, but successive paragraphs of the same Style are also enclosed in <ul> and </ul>.

The default Actions for Paragraph Styles are Delete tag, Delete text and Don't touch.

If you use the Modern Template, each paragraph which uses Delete tag or Don't touch as Style Action is enclosed in <p> and </p> during export.

Inline Style Actions

Inline Style Actions can either be regular Inline Style Actions or Reference Style Actions. Regular Inline Style Actions work just like Paragraph Style Actions: the text range is enclosed by the markup. For instance, you can apply the Style Action Emphasize to the Inline Style “Emphasize” and thus every string that has this Inline Style applied is enclosed in <em> and </em>.

Reference Style Actions

Using Reference Style Actions, you can include images, external links, and references in your exports. Every Reference Style Action expects a certain format, which can be found by clicking on Show available Actions…. This section explains the Reference Style Actions for the Modern Template. The Actions for the other Templates are largely the same.

One such Reference Style Action is Link. This Style Action expects the following format inside its Inline Style: key-description (key and description being placeholders). In addition to that, you need to add a Note to the Notepad which starts and ends with the start tag and end tag of the Inline Style, respectively. In the case of the Link Style Action, the expected format is key-link. If you apply an Inline Style for links, which has (( as start and )) as end tag, you could to insert ((link1-The Soulmen)) in the text and ((link1-http://www.the-soulmen.com)) as a new Note to denote a link to “http://www.the-soulmen.com” with “The Soulmen” as description. The output for the Modern Template would be <a href="http://www.the-soulmen.com">The Soulmen</a>.

Another Reference Style Action is Image. Using this Action, you can export images, which can be referred to from within the paragraph and are displayed after the paragraph. Inserting images is quite similar to inserting links. Inside the Inline Style, you just need to insert a key (e.g., img1). You also need to create a new Note which has the format key-image-description. The key placeholder must be the identical to the key in the text, i.e., img1 in our example. image refers to the actual image, which you can copy & paste or drag & drop into the Note. The last placeholder, description, must be a textual description of the image, which is displayed below the image. You need to put a dash (“-”) between the key and the image and between the image and the description. Upon export, the Inline Style will be replaced by Image index, where index is the index of the image in the Document. The actual image is displayed below the paragraph with the textual description below.

The last two Reference Style Action are Footnote and Reference, which work largely the same way. Image you write a text and insert a quotation or refer to a source. With the “Reference” Style Action, you can add a reference (like “[Mood04]” or “[Burgess73]”) after the quotation and put the full reference at the end of the page. You just need to insert a key into the Inline Style. Additionally, you need to create a Note which contains same key and the full reference separated by a dash (“-”). Don't forget to enclose the Note in the start and end tag of the Inline Style.

The default Actions for Inline Styles are Delete tags, Delete Text, and Don't touch.

Marker Actions

When using the default Templates, the Style Actions for Markers are the same as the regular Inline Style Actions, such as Emphasis, Strong, or Underline. In addition to these Actions, you can also use Delete Text, Enclose in and Don't touch for Markers. “Enclose in” is especially useful if you want to set the markup for a Marker on the fly. Just enter the start and the end tag separated by “ - ” (space dash space) in the “Character(s)” column.

Creating Custom Templates

The Web Export allows you to create and edit your own Templates, which you can use to export your Documents. The following chapter gives an extensive introduction to the Template Manager and the Template Editor, which include all the necessary tools to create and edit Templates.

The Template Manager

The Template Manager

The Template Manager is for creating, duplicating, and deleting Templates. To get to the Template Manager, open the Template selection popup button and click “Manage Templates…”. A list of the available Templates, is then displayed in the sheet. The default Templates cannot be edited or created. However, they can be duplicated, which creates a copy of the selected Template as a custom Template (which can then be edited). Custom Templates can be edited and deleted. Additionally, a new Template can be created from scratch using the “New” button. If a custom Template is selected, you can open the Template Editor by clicking on the “Edit…” button.

Hint: The easiest way to get started in editing Templates is duplicating one of the default Templates (e.g., Modern) and then editing it.


The Template Editor

The Template Editor is the central place for all your editing needs. Here you can change the structure of your template files, add Style Actions, and edit Parameters. The Editor is split into three tabs: General, Structure, and Actions. Additionally, the tabs “General” and “Actions” include the Placeholder panel, which displays the relevant Placeholders and allows editing Parameters.


The General tab

In the tab General, settings such as the name, the author, and the description of the Template can be edited. In addition, a preview image can be dragged into the box on the right.

On the bottom, a path to a shell script can be specified. This script is executed after all Documents are exported. Therefore, this script can be used to do post-processing, such as compressing all exported files into a zip file. See the section “Post-processing” for in-depth coverage.



The Structure tab

The second tab, Structure, allows editing all template files. The table on the left displays a list of all files, which are either exported once per export, or exported once per Document. An example for the former are index pages, or a cascading style sheet (CSS) file. Usually, only one file is exported once per Document. Using the buttons at the bottom, you can create, duplicate, and remove files. If you create a new HTML file, the content of the file is automatically filled with typical HTML elements.

The right-hand side allows you to specify the path to which the template file will be exported. For instance, the index page will usually have the path index.html. You can put placeholders (we'll get to them later) into the export path. This is important for setting the export path for files, which are exported once per Document. For example, you can export these files to pages/{{document.name}}.html, where the string {{document.name}} is replaced by the respective titles of the Documents during export. Below the export path text field, the text editor is located.


The Actions tab

The last tab, Actions, contains all Style Actions of the Template. If you select one, its properties can be viewed on the right-hand side. Actions can be added, duplicated, and deleted using the buttons at the bottom.



The Placeholder panel

The Placeholder panel is always present in the “Structure” and “Actions” tabs. It displays a list of available placeholders, which can be dragged into the main panel. In addition to drag & drop, you can set your cursor to a certain position in the text field (inside the main panel) and then double click the placeholder to insert it at the position of the cursor.

Placeholders

Before we go into detail of editing Templates, let me explain what placeholders are first. A placeholder is a variable that is replaced by a literal string during export. A placeholder can also contain a command that is processed during export. The latter is covered in detail in the section “Commands”. In the Web Export, placeholders always begin with {{ and end with }}. If the placeholder is a variable (and not a command), they can only refer to a Parameter, a property of the current Document or to a Reference (this is a special case which will also be discussed later).

All allowed placeholders are displayed in the Placeholder panel. You can simply drag them into the text. This way, you don't need to remember the placeholder names. If you want, you can also enter a placeholder manually by typing {{, then the name of the placeholder, and then }}. In the Text Editor in the Structure tab and in all text fields, Placeholders can be edited by double-clicking them.

Parameters

Parameters can be edited in the Placeholder panel. Simply select one of the Parameters, and its properties will appear on the bottom of the panel. To add a Parameter, click the “add” button and select the required type. For almost all Parameter types, a default value can be set, which is then used when no other value is set explicitly. For the “List” Parameter type, a list of description/value pairs can be edited. Finally, the “Image” Parameter type has a property “path”, which needs to be set to the relative path where the image is to be exported to. For instance, if “path” is set to image, the inserted image will be exported to this path with the file extension (e.g., “.png”) appended.

Document Properties

For each Document, you can access a number of properties (such as the title or the content of the Document), which are also available in the Placeholder panel. Simply drag them at the desired position in the text.

Commands

You can use five commands to insert content during export: IF, FOR, ENC, LINK, and LOC. Four of these five commands are also used in the following source code:

IF can be used to enable or disable a part of the code, depending on the value of its variable. If the variable evaluates to true, the code following the IF statement until the END placeholder (which is not replaced by any value, it is just removed during export) is included in the exported file(s). If it evaluates to false, the section won't show up in the export. For instance, the string “TOC” (line 1) refers to the Parameter “Table of Contents”, which is represented by a checkbox with the same label in the user interface. If the checkbox is enabled (and thus, the variable is set to true), lines 2 to 6 are included in the export.

The IF statement can also contain a complex boolean expression, which is evaluated during export. For instance, you can check whether the Parameter “Title” is set to a certain string: {{IF TITLE == 'A Certain string'}} ... {{END}}. You can find a syntax reference in the NSPredicate Programming Guide under “Basic Comparisons” and its following sections.

The FOR statement iterates over an array of data. In each iteration, one element of the array is assigned to a special variable.

This is most useful if you want to iterate over all exported Documents. In each iteration, you can access the properties of one Document. The order is the same as the order in the Browser.

To make this more concrete, the syntax of the FOR statement is as follows: first the string FOR, then the name of the variable, then IN and then the name of the array (in short: FOR variable IN arrayName).

The name of the array of all Documents is documents. You can set the name of the variable as you like. In the code example above, document is used (see line 4). Between the FOR statement and the END placeholder (i.e., inside the FOR loop), you can use this variable. As you can see in lines 4-6 of the code, FOR iterates over all documents and in each iteration, the current Document is assigned to the variable document. In line 5, this variable is used to print the title of the Document. The purpose is to print the names of all Documents to create the table of contents.

In the second half of the code (lines 10-16), FOR iterates over all Documents again, this time printing the title of the Document ({{document.name}}) followed by the content of the Document ({{document.text}}).

The FOR loop also has two optional arguments: WHERE and ORDER BY. The first one can be used to add expression similar to the IF statement to the loop. ORDER BY can be used to order the data over which the loop iterates (like the exported Documents) by a property. For instance, the following snippet prints all Document names, whose status is “Done” and orders them by timestamp:

ENC stands for Encode, meaning that the ENC statement can encode a certain string so that this string is safe to use, e.g., in a link. The string to be encoded must be supplied after the ENC keyword. After the encoding process, whitespace is replaced by dashes (“-”) and all illegal characters (such as :, ?, /, #) are removed.

If you look at line 5, the title of the document ({{ENC document.name}}) is encoded. This is important because links must not contain any whitespace or illegal characters. Since two Documents with the same title may be exported at once, you should always add the index of the Document ({{document.index}}) to the link. The index of the Document is generated during export and depends on the order of the Documents, i.e., the first Document will get the index 1, the second Document will get index 2, and so on. If the name of a Document is “Finding Nemo: where did they look?”, {{ENC document.name}} for that Document is converted to Finding-Nemo-where-did-they-look during export.

LINK can be used to link to Documents. If you enter {{LINK document}}, the relative path to the current document is returned. This is especially useful for linking to Documents. Fo instance, you can type <a href="{{LINK document}}">{{document.name}}</a> to get a link to the Document.

The last statement, LOC, is used for localization. Since this is a very advanced topic, it will not be covered any further.

In conclusion, these five commands allow you to dynamically insert (and remove) content and adjust it to your needs. You can use them in every file (even in CSS files!) since all template files are processed during export. Furthermore, you are free to nest IF and FOR statements as long as you don't overlap them. Just don't forget to terminate them with the END placeholder!

Template Files

All files in the tab “Structure” are exported during export, either once per Export, or once per Document. These files are called template files. If you build an HTML Template, these template files look pretty much like regular HTML files with some placeholders inserted in them. Using these placeholders, the content of a Document, a table of contents or a header, etc. can be inserted during export.

The following sections will explain how to create template files by adding Parameter, Document property, and command placeholders to an already existing HTML file.

Inserting Parameter Placeholders

The following lines show an excerpt from a template file of the Minimal Template:

As you can see, this passage looks just like regular HTML with some placeholders (printed in bold) inserted. The names of the placeholders all refer to their respective Parameters. Upon export, these placeholders are replaced with their values. For instance, if the Parameter Metatag is set to <meta name=“generator” content=“Ulysses 2.1” />, exactly this string will be inserted.

Inserting Document Properties

For template files, which are exported once per Document, you can access the properties of the current Document directly. The following code snippet shows examples of the use of Document properties in template files:

This snippet is pretty self-explanatory: upon export, {{document.name}} is replaced with the title of the document, {{document.excerpt}} with the excerpt and {{document.text}} with the actual content (including markup from the Style Actions).

Please note that you can only use Document properties right-away for template files which are exported once per Document. Template files, which are exported once per Export, need to iterate over the documents using {{FOR document IN documents}} and access the document properties between this statement and the corresponding {{END}} statement.

The Info Button

To check if your template file is correct, you can click the info button to see if the file includes any errors.


Actions

The tab “Actions” lists all existing Style of the Template. If you select an Action, its properties are displayed on the right-hand side. Every Action includes a property “Result”. During export, the contents of all Styles which are assigned to this Action will be replaced by the string in the “Result” text field. The contents are inserted at the position of the {{}} placeholder. For example, a Paragraph Style for the Action “Heading 1” might have the following result: <h1>{{}}</h1>. Thus, the text of the paragraph is enclosed in <h1> and </h1>.

Paragraph Style Actions

Paragraph Styles Actions have two different kinds of types, which can be chosen from the popup button: Simple and Grouped. The former type works just as explained above. In the latter type, subsequent occurrences of the same Paragraph Style will be grouped. Each paragraph is grouped using the placeholder in “Result”, and subsequent paragraphs are grouped using the placeholder in “Grouping”. If the last option, “Do not touch content”, is enabled, Inline Styles and Markers inside the Paragraphs with this Style will be left as-is. This is especially useful for sections containing code or text to be printed verbatim. Each Template also has a default Paragraph Style Action, which is applied when no Paragraph Style is applied to a paragraph.

Inline Styles Actions have one of the three following types: Simple, Formatted, or Linked with Notes. The first one is identical to the Simple style of Paragraph Styles. The latter two are used for Reference Styles (i.e., an Inline Style that contains a reference).

Formatted Inline Style Actions

Using Formatted, you could create a very simply Link Style Action. For instance, set the text field “Expected Text Format” as follows: {{link}}-{{description}}. This means that the user is expected to enter the link (like http://www.the-soulmen.com), then “-”, and then a description of the link. The Web Export parses this string and saves “link” and “description” as variables, which you can use during the export. For instance, you could then set the value of “Result” to <a href=“{{link}}”>{{description}}</a>. If you use an Inline Style “Link ID” with start tag “((” and end tag “))”, you would enter ((http://www.the-soulmen.com-The Soulmen)) in the Editor of Ulysses. Upon export, this string would be replaced by <a href=“http://www.the-soulmen.com”>The Soulmen</a>.

Linked text inside Styles with Notes

Linked with Notes is an extension of the Formatted type. Instead of just formatting the text inside the Style, you can link the text to a Note in the Notepad. This is useful if you want to insert a longer text or an image. With Linked with Notes, you not only specify the formatting inside the Style in the Editor, but also of the Note. For example, you could change the value of “Expected Text Format” to {{key}} and the value of “Expected Note Format” to {{key}}-{{description}}-{{link}}. Therefore, you could enter ((link1)) in the Editor and create a new Note with the string ((link1-The Soulmen-http://www.the-soulmen.com)) (please note that you always need to enclose the Note in the start and the end tag of the Reference Style). During export, the Exporter matches the content of the placeholders of “Expected Text Format” (in this case, “link1”), to Notes which are enclosed in the start and end tags of the Reference Style. You are free to use that Note more than once, for instance if you use that link multiple times in a Document.

Inserting images and other media into exported files

The good thing about Notes is that you cannot only insert plain text, but any kind of media (such as images, sounds, or movies) or even files. To include media or files, simply enable the checkbox Floating Element. It's called Floating Element because the inserted media is usually not inserted right at the position where the Reference Style is located, but before or after the paragraph. It thus “floats” before or after the paragraph. Media are only inserted once, and referenced once you mention them again in the text. You can use this type to insert images into your exported Documents. For this, set up “Expected Text Format” and “Expected Note Format” first. You could for example set “Expected Text Format” to {{key}}, “Expected Note Format” could be {{key}}-{{image.data}}-{{description}}. Thus, the text inside the Reference Style is just the key, the corresponding Note consists of the same key, “-”, the inserted image (which is inserted using copy & paste or drag & drop), another “-”, and a textual description. Alternatively, you can also drag in the “Media Data” placeholder from the Placeholder panel. Finally, you could set the value of “Result” to a string like Image {{key}}. Therefore the text of the Reference Style is replaced by the string “Image” followed by the key.

You now need to deal with the following two issues: (1) where should the image file be located in the export and (2) where should the image be placed inside the HTML file?

Issue (1) is addressed by adding a path to the image. You can define this path in the text field “Media Export Path”. The path could be for example be images/{{document.name}}/{{key}}, i.e., the image that you inserted into the Note is written to images/Introduction/img1 (assuming the title of the Document is “Introduction” and the key of the image is “img1”).

To resolve issue (2), you probably don't want to insert the image right at the place where the image is referenced (i.e., where you put the Inline Style for the image), but before or after the paragraph of the whole Document. You can simply set the position using the popup button “Position”. Finally, you need to set what the floating element will contain after the export in the field “Floating Element”. In the example of the Image Reference Style Action, you could set the value of “Floating Element” to <img src=“{{image.path}}” alt=“{{description}}” />. Therefore the image is inserted with its “src” attribute pointing to the location of the image and the “alt” attributed being the textual description.

You can customize the values of “Expected Text Format” and “Expected Note Format” so that they fit into your workflow. You don't need to separate placeholders with “-”, you can use as many placeholders as you want and there are no restrictions placed on which placeholders need to go into “Expected Text Format” and which should go into “Expected Note Format” (except that no media or files are allowed in the Editor since it's plain text only). At least one placeholder of “Expected Text Format” also has to appear in “Expected Note Format” in order to connect them. During export, the first Note in which matching values are found, is used.

Storing Reference Style Data

Finally, you can also store all information of Reference Styles in a variable and use it later on. For instance, you could collect all occurrences of footnotes, and iterate over all footnotes at the bottom of the page. In the Template Editor, you can this variable by enabling the checkbox “Store all Occurrences in Variable” and enter a value. For instance, if you set it this value to references, “Expected Text Format” is set to {{key}}-{{shortReference}}, and “Expected Note Format” is set to {{key}}-{{longReference}}, you can access the values of the variables later as references.key, references.shortReference and references.longReference.

Here's a typical use case: you reference a source in the text by putting a short reference, such as “[1]” or “[Hawking97]” into the text, possibly more than once. At the end of the Document, you want to append a list of all References in the Document. You can now use a FOR loop to iterate over all references:

Please remember that after the FOR loop, i.e., after the corresponding END placeholder, you cannot access the variable anymore.

Every time you loop over an array, you also have access to the properties @index and @count. During the export, this former property is replaced by the index of the current element in the array, while the latter is replaced by the total count of elements in the array. You could extend the last code snippet to use the @index property:

Marker Actions

Marker Actions are identical to those of simple Inline Style Actions. Simply use the “Result” text field to insert the “Text” Placeholder and adjust the output.

Validation

Every time you open the Web Export or edit a Template, the Templates are checked for correctness. If a Template is not valid, a little warning sign appears in front of the Template in the popup button. If you select the Template, a sheet is shown, which displays the specific errors in a table. This way, you can easily find out which kind of errors are in your Template and where they are located.

Additionally, if a text field in the Template Editor is incorrect, its info button turns red and upon click, you can see what went wrong.

Post-processing

After exporting, you can post-process the exported files using scripts. The choice of the programming language is left to you. As long as you have an interpreter installed, it will be executed. By default, scripts are executed as Bash shell scripts. To set the script file, you can simply drag a file into the shell script text field in the tab “General”. The file will be copied to the Template folder (if a file with the same name exists, it will be overwritten). Additionally, you can click the “Reveal in Finder…” button below the text field and drag & drop it there.

During export, the files are first written into a temporary directory, in which the script can then alter the files. If the script exits successfully, all files will be copied to the destination directory.

For the script, you can use the following environment variables:

< ePub