Typo

Summary
=======

*Obsidian-Typo* is a collection of CSS snippets for *Obsidian*, refining
the typography of the rendered markdown texts.  It focuses mainly on the
way how whitespace is displayed by *Obsidian*, without affecting the
markdown code of the documents.  It is predictable, free of heuristics, and
reversible by deactivation of the snippets.

*Obsidian* is a Markdown (``.md`` files) editor.  It uses an HTML-based
interface employing *Electron*.  Due to the nature of an HTML-based GUI,
*all* interface components of *Obsidian* can be styled by CSS (*Cascading
Style Sheets*).  Style sheets can be given either as *themes* or as *CSS
snippets*.  While writing texts with Obsidian, I found the rendering of
*whitespace* often inadequate, especially whitespace around headlines, but
also in places like in the surroundings of enumerations and itemisations.
Presented here is *Obsidian-Typo*, a set of CSS snippets implementing
primarily typographic rules related to whitespace, but also addressing a
few topics more.  *Obsidian* distinguishes between *reading mode* and
*editing mode*.  *Obsidian-Typo* brings these two very close to each other,
implementing all major achievements already in editing mode.
*Obsidian-Typo* is *not* a theme.  It is of no influence whatsoever on the
general UI appearance, and addresses *only* the typography in *reading
mode* and in *editing mode*.  *Obsidian-Typo* is designed in such a way,
that the application of its CSS codes to a given *Obsidian Vault* does not
require adaption of the markdown sources for the vault's documents.  It
further compensates many adjustments made before using additional blank
lines *from the beginning* wherever possible and appropriate.  Because with
*Obsidian-Typo* the typography is optimised already in editing mode, the
usage of *Obsidian* benefits from *Obsidian-Typo* early on, improving user
experience with Obsidian from the beginning of drafting Obsidian documents.

The remainder sections of this README are structured in the following way:

1.  In the next section, a *Demonstration* of rendering some sample MD code
    is given by providing the results of:

    a)  using *Obsidian-Typo* (with the Default theme);
    b)  working without *Obsidian-Typo*, using either the vanilla Default theme
        or kepano's *Minimal* theme.

2.  Below the *Demonstration* section, a short instruction for how to
    install *Obsidian-Typo* to an Obsidian Vault is given.

3.  For further reference, the *Documentation* might be a good starting
    point, which it is mentioned in the end of this README file.


Demonstration
=============

Sample Markdown Code
--------------------

The following Markdown code is to be displayed by Obsidian:

.. code:: markdown

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
    nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
    sed diam voluptua.  At vero eos et accusam et justo duo dolores et ea
    rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem
    ipsum dolor sit amet.
    # Headline
    Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse
    molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero
    eros et accumsan et iusto odio:

    1. Dignissim qui blandit praesent luptatum zzril delenit augue duis
       dolore te feugait nulla facilisi.
    2. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
       nonummy nibh euismod tincidunt ut laoreet.

    Dolore magna aliquam erat volutpat praesent luptatum zzril delenit
    augue duis dolore te feugait nulla facilisi.

    # Headline with Whitespace

    Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper
    suscipit lobortis nisl ut aliquip ex ea commodo consequat.

    Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse
    molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero
    eros et accumsan et iusto odio dignissim qui blandit.

In this listing, additional linebreaks have been added to keep the MD code
readable without horizontal overflow.  In the file which is actually *used*
for this demonstration, each paragraph is provided on *one single line*.

There are two headlines presented here:  The first one (*"Headline"*) is
written directly adjacent to the continuous text around it, while the
second one (*"Headline with Whitespace"*) is padded by one single blank
line above and below.


Rendering using *Obsidian-Typo*
-------------------------------

In this demonstration, *Obsidian-Typo* is used with the Default theme.

With *Obsidian-Typo* enabled, the results in live mode are:

.. image:: Demo/Typo-Live.png
    :alt: Obsidian-Typo in Live mode

and in preview mode:

.. image:: Demo/Typo-Preview.png
    :alt: Obsidian-Typo in Preview mode

The styles introduced by *Obsidian-Typo* provide unified whitespace around
the two headlines, result in an appropriate separation around the
enumeration (in the section below the *Headline*) and to an adequate
spacing between the two paragraphs in the second section (below *Headline
with Whitespace*).

The blank lines surrounding the *Headline with Whitespace* are of no effect
to the typeset result, while they remain unaltered in the MD sources.

These findings apply both to the editing mode display as well as to the
reading mode.


Rendering with the Default Theme
--------------------------------

Rendering in live mode with the vanilla Default theme looks like:

.. image:: Demo/Default-Live.png
    :alt: Default theme in Live mode

while in preview mode the result is:

.. image:: Demo/Default-Preview.png
    :alt: Default theme in Preview mode


Rendering with kepano's Minimal Theme
-------------------------------------

With the pure Minimal theme, the given MD code is shown in live mode as:

.. image:: Demo/Minimal-Live.png
    :alt: Minimal theme in Live mode

and the preview is:

.. image:: Demo/Minimal-Preview.png
    :alt: Minimal theme in Preview mode


Installation
============

*Obsidian-Typo* is provided as a set of CSS snippets which can be installed
to a given Obsidian Vault.  These CSS snippets are located in the ``CSS``
folder, which is located directly besides of this README in the root
directory of the *Obsidian-Typo* repository.  The installation of
*Obsidian-Typo* consists in the following procedure:

1.  Each Obsidian vault carries a dot-directory ``.obsidian`` in its root
    directory.  CSS snippets like those provided by *Obsidian-Typo* are
    made available by copying them to a subfolder ``snippets`` of the
    ``.obsidian`` folder.  They are always installed *per vault*.  When the
    vault in question exists in ``/path/to/vault/``, the corresponding
    directory is ``/path/to/vault/.obsidian/snippets/``.  The ``snippets``
    folder does not exist in newly created Obsidian vaults in the
    beginning, it needs to be created once.

2.  After having installed the CSS snippets, they need to be *enabled* in
    the *Appearance* pane of the vault's settings in Obsidian.  The
    switches used for this purpose are located in the bottom end of the
    *Appearance* pane.

Nothing beyond these two steps is required to install *Obsidian-Typo*.  To
revert back to the state without *Obsidian-Typo*, the snippets can be
either *deactivated* in the *Appearance* pane, or they can be just
*removed* from the ``snippets`` folder.

Further hints on the installation process are provided in the documentation
referred to below at the end of this README.


Documentation
=============

Documentation is maintained in a separate repository and is distributed as
a ZIP archive (``Typo-Doc.zip``) located in the root directory of this
repository.

The documentation is licensed independently from the MIT-licensed CSS code.