Document Styles

What are Notebooks’ Document Styles?

Document Styles determine the overall appearance of formatted documents and rendered Markdown documents. It defines font and font size, sets hyphenation, line spacing, size, weight and color of headings, alignment and decoration of images, the exact appearance of lists and checklists and much more. By changing the document style you quickly change a document’s appearance without touching any other setting. 

The document styles that come with Notebooks dynamically pick up and apply a document’s attributes. So if you choose a new font, for example, Notebooks embeds this information in the document style on the fly, ensuring that the document uses the correct font.

From a more technical point of view, Notebooks’ document styles are Cascading Style Sheets (CSS), which are commonly used to describe the presentation of websites and specify how elements are rendered on screen, on paper and other media. As Notebooks‘ formatted documents are HTML, they can use almost everything provided by CSS.

• What are Notebooks’ Document Styles?
• Notebooks’ Built-in Document Styles
• How Notebooks Selects a Style
• Custom Document Styles
• Create Your Own Document Styles
  • Inherit from Existing Styles
  • Write your own Document Style
  • Placeholders for Attributes
  • CSS Variables
• Dark Mode Support
• Solarized Appearance

Notebooks’ Built-in Document Styles

Notebooks includes a set of pre installed styles to choose from. We provide more styles in the download area of our website which demonstrate certain usage scenarios or which may not be relevant for all users. Still, feel free to grab and install them.

Here is a short description of the pre installed styles:

Style	Description
Basic	This style is the foundation of all other styles. It dynamically includes attributes, defines the functionality of checkboxes, footnotes, citations, page breaks and more.
Minimalist	Adds just a few details to Basic, but mostly sticks with the browser defaults.
Default Theme	This is Notebooks‘ “signature style”.
Monochrome	Like Default Theme, but without colors.
Source Code	Adds syntax highlighting to Default Theme.
Scientific	Based on Source Code, uses numbered chapters.
Scientific + MathJax	Adds support for MathJax.
Scientific + KaTeX	Adds support for KaTeX mathematics.
Uppercase	Default Theme with uppercase headings (H2 and H3).
Handbook	This is the style we use for Notebooks‘ handbooks (more or less).
Novel	An older version, available for compatibility. It resembles the layout of a classic book.
Legacy	Another older version, still here for backward compatibility.

How Notebooks Selects a Style

When you open a formatted document or a Markdown document, Notebooks needs to figure out which document style to apply. The Document Style is an inherited attribute which you can set at multiple levels:

1. The global default is set in Notebooks’ settings. This style is used when no other style has been specified.
2. In any book’s info, you can select a different style which overrides the global default and is used for all documents in this book.
3. Finally, you can pick an individual style for a single document (in its info). This style overrides the global default and any style which may be set of any of the document’s parent books.

When figuring out which style to use, Notebooks first looks at the document’s info, then searches up the hierarchy of parent books. If it reaches the top level without finding a specific setting for the document style, Notebooks falls back to the global default.

Custom Document Styles

If you want to go beyond the set of Notebooks’ pre installed styles and you are familiar with CSS, you can easily define and add your own styles. We provide a couple of styles for download which you can use as a starting point, but before we dive into customizing document styles, let us look at how to install and make them available to Notebooks.

Notebooks expects custom styles in the hidden book NBResources/CSS at its top level. This makes sure that styles you add on one device automatically become available on your other devices, too. All .css files you add to this folder automatically appear in Notebooks’ list of document styles.

As the book is hidden by default, gaining access to it slightly varies depending on the device you use.

On your Mac

The simplest option is to drag and drop a .css file onto the Notebooks icon in the Dock. Notebooks will ask whether you want to install the file as document style and place it into the correct folder for you.

If you want a little more control, you can open and access the folder NBResources/CSS from Finder. Notebooks provides a dedicated menu action Notebooks > Show Resources Folder… to open a Finder window and display the content of NBResources. If the subfolder CSS does not yet exist, simply create it, and then add your own .css files.

On your iPhone or iPad

You can create and edit custom document styles directly from Notebooks‘ settings:

1. In’ Settings > Write and Edit > Document Style, scroll to the bottom and select Add Your Own.
2. An editing window appears and displays the minimum required settings for a style. Add and modify the style sheet to your liking. When you are done, tap Save to make your new style available in the list of installed styles.
3. You can open and edit your existing document styles from this list as well.

Alternatively, you can open and edit your custom styles like regular documents:

1. Search for NBResources, starting at Notebooks‘ top level. The hidden book will appear as search result.
2. Open it, navigate to CSS and work on your styles.

Create Your Own Document Styles

Now that you know how and where to store your document styles, let’s look at how to customize them. The best way to learn about customization is to inspect the provided samples. You will notice that most samples adjust a few aspects only and don’t define the style from scratch. Instead, they include and inherit from existing styles.

Inherit from Existing Styles

While you can create a document style from ground up and fully customize the appearance of your documents, you probably just want to tweak a few details in most cases: change alignment and size of headings, accent colors, borders etc. So instead of writing a complete style sheet or duplicating and modifying an existing one, you can build upon one you already have by including it like this:

<style type="text/css">

@nb_include: "Default Theme";   /* The style to inherit from */

h2 {
    text-transform: uppercase;  /* Display heading 2 in UPPERCASE letters */
}

</style>

This is already a complete custom style based on Notebooks‘ Default Theme, with the addition to transform all headings of level 2 (Notebooks describes them as Chapter) to uppercase. Everything else remains as defined in the Default Theme.

You can make your style even more compact by skipping the <style type="text/css"> and </style> tags, as Notebooks adds them for you if necessary:

@nb_include: "Default Theme";
h2 { text-transform: uppercase; }

The most basic custom style which makes sure to pick up attributes and settings and correctly renders checklists, would be this:

@nb_include: "Basic";  

Rules for Including Styles

• Use the @nb_include: "<style>"; directive to embed the given style at this exact location in your custom style. Please note the trailing semicolon.
• The name of the style to include must be given in quotes.
• You can skip the filename extension, so "Default Theme" and "Default Theme.css" are the same.
• You can use multiple @nb_include: directives to include different styles.
• A style can inherit from any pre installed style, but also from your own styles.
• The position of the include directive is essential, because the included style may override settings defined above, and it may be overridden by settings defined further down.
• Included styles can include other styles as well; Notebooks makes sure a specific style is included only once.
• You can skip the <style type="text/css"> and </style> tags, unless you want to include a <script> in your custom style. In this case you need to add all tags in order to correctly delimit and specify the components.
• The option to inherit from existing styles requires at least Notebooks 10 on your iPhone or iPad and Notebooks 2 on your Mac.

Write your own Document Style

If you prefer to create your own document style from scratch or reuse a style from elsewhere, you may still want to dynamically add attributes like font and font size, hyphenation, text alignment etc. The quickest way to achieve this is by including Notebooks‘ Basic style,

@nb_include: "Basic";  

but if this still contains too many settings that you do not want, you can pick specific attributes by adding their placeholders to your style.

Placeholders for Attributes

Before Notebooks applies a document style to a formatted document, it looks for placeholders and replaces them with the current attribute values. This allows you to use attributes in your style without knowing their value. Here is a list of all placeholders with special meaning in Notebooks.

/* Notebooks replaces the placeholders below with the corresponding settings
   on the fly. */
body {
    font-family:    **NotebooksFont**;
    color:          **NotebooksFontColor**;
    font-size:      **NotebooksFontSize**;
    line-height:    **NotebooksLinespacing**;
    background-color: **NotebooksBGColor**;
    background-image:url('**NotebooksBGImage**');
    text-align:         **NotebooksTextAlign**;
    -webkit-hyphens: **NotebooksHyphens**;
}

CSS Variables

Notebooks‘ document styles use several variables, so called CSS custom properties, primarily for specifying color schemes. If you want to change the colors used for headings, checkboxes etc., these are the variables to override:

/* This section defines the global color theme; reuse and adjust these
   variables in your own theme to change colors */
:root {
    --theme-color: #<col>;          /* color for headings and emphasis */
    --checkbox-color: #<col>;       /* color for the checkboxes*/
    --checkbox-done-color: #<col>;  /* DONE checkboxes */

    /* The Default Theme adds a few more variables: */
    --dimmed-divider-color: #<col>; /* used for dividers, tables, etc. */
    --accent-color: #<col>          /* to colorize blockquotes, links, etc. */
}

Here is a quick example of a custom style which sets the theme color to red:

@nb_include: "Default Theme";
:root {
    --theme-color: firebrick;
}