Document Styles

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
• Custom Classes (Captions, Sidebars, etc)
  • Assign Classes to Text Blocks
    • Formatted Documents
    • Markdown
  • Create and Use Your Own Classes
    • Define Custom Classes
    • Declare the Classes You Want to Use
    • Override Default Classes

Document Styles determine the overall appearance of formatted documents and rendered Markdown. They define 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.

Notebooks‘ document styles also contain additional text styling options like Caption or Sidebar to control the appearance of your documents, in addition to the traditional styles like headings, bold, italic etc. We generally refer to these options as custom classes. Like the style itself, classes are customizable, which give you full control over your documents’ appearance. – Custom classes were introduced in Notebooks 12.6 / 3.6.

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, paper or on other media. As Notebooks‘ formatted documents are HTML, they can use everything provided by CSS.

Sometimes you may see Document Themes instead of Document Styles, but both terms refer to the same thing.

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”.
Callouts	Based on Default Theme, adds callouts like Note, Hint and more.
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.

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;
}

Custom Classes (Captions, Sidebars, etc.)

Custom classes provide styling options that go beyond the traditional styles like headings, bold, italic etc. Caption, Description, Sidebar are a few commonly used examples, and they are not limited to controlling font and size of the text, they can also control borders, layout, size, position etc. Notebooks‘ default document styles already contain a few of these classes (Handbook currently provides most), but as we are working with standard CSS, you can add and your own classes as well.

Assign Classes to Text Blocks

Just as you assign a heading level to text, you can assign classes to text. Please note that these classes can be used for blocks of text, but not for single words or, more generally, inline text:

Formatted Documents

In formatted documents, you find the available classes at the bottom of the paragraph menu, and you assign a style simply by choosing it from the menu. A checkmark in the menu indicates that the text at the current cursor position already uses that style, so selecting the menu entry again turns the style off.

Markdown

In Markdown, use the following notation to assign a custom class to the subsequent text:

> %caption%
This is the text that should appear as caption.

The closing percent sign must be the final character on the line, with no space or other characters following it.

This sample translates to

<div class="caption">This is the text that should appear as caption.</div>

As it is difficult to know which classes the currently selected document style supports, Notebooks assists you with autocompletion.

• Type > %<TAB> to get a list of available classes.
• Type > %cap<TAB>, for example, and Notebooks could autocomplete that to > %caption%, if the class is available.

Create and Use Your Own Classes

You can customize and add your own classes just as you can customize the whole document style. This involves two steps: Definition and Declaration.

Define Custom Classes

The definition of classes follows standard CSS rules and guidelines, so you can easily reuse classes you may already have in other applications. Here is an example of how you could define a Caption:

.my_caption {
    font-size:  0.9em;
    font-style: italic;
    justify-content: center;
    margin-top:  0.5em;
    padding-bottom: 0.2em;
}

Caption: This sample defines a class my_caption, with a slightly smaller and italicized font,sets text alignment to center, and applies top and bottom margin and padding.

With that in place you are almost ready to use your new style in Notebooks, but there is one additional step.

Declare the Classes You Want to Use

Notebooks does not automatically display all classes defined in a stylesheet. This is because you may be reusing a stylesheet from another source that includes classes not intended for editable documents. Instead, you choose which classes should be available for use declaring them at the beginning of your stylesheet like this:

@nb_classes: my_caption;

This line tells Notebooks to make the class my_caption available in a formatted document’s paragraph menu, and also in a Markdown document’s autosuggestion list for classes. You can declare multiple classes as a comma separated list.

As document styles can inherit from others, there may be multiple @nb_classes declarations. Notebooks adds all declared classes to its list, keeping them in the sequence they appear in the stylesheet.

Override Default Classes

In the example above we defined a custom caption. However, Notebooks already defines and declares a class Caption, so you would end up with two similar classes. You can use a specific syntax to handle that:

@nb_classes: nb_reset, my_caption;

The pseudo class nb_reset tells Notebooks to forget all classes that it collected in the style sheet so far, and start anew by adding my_caption. This way you can exclude classes you don’t want, but you can also change the sequence in which the classes appear in the menu.

The pseudo class nb_reset instructs Notebooks to discard all the previously collected classes from the stylesheet and start fresh – only adding my_caption in the example above. This allows you to exclude unwanted classes and control the order in which they appear in the menu.