+
Obsidian	+	Pandoc

Obsidian & Pandoc

We have dedicated two posts to Obsidian, describing its features and potential.

Obsidian allows the installation of third-party plugins (Community plugins) made by developers outside Obsidian.

Among the numerous third-party plugins, there is also “Obsidian Pandoc Plugin” by Oliver Balfour, through which it is possible to use Pandoc inside Obsidian.

With this plugin, you can realize a good integration between Obsidian and Pandoc, which is this new post’s subject.

We’ll reserve an ad hoc paragraph on Pandoc and immediately dwell on the updates released for Obsidian, particularly regarding our previously published posts.

Obsidian updates

Obsidian receives frequent updates, and it is difficult to describe them all; a list is available on the Official Obsidian Forum.

In fact, we had published two posts about Obsidian specifically:

• Obsidian part 1 dated 16/12/2021;
• Obsidian part 2 dated 20/12/2021.

On 12/21/2021, just after our last post about Obsidian was published, an update was released.

As we write this post (6/1/2022), another update was released, and, therefore, the current version of Obsidian is 0.13.19, as announced by Obsidian with the following tweet:

The new features of this new version (0.13.19) are:

• Support embeds in plugin blocks like Admonition and Dataview
• Support for headings in lists
• Persistent undo history when switching notes
• Search highlights and multiple cursor in Vim mode

To complete what we’ve already written about Obsidian in our previous posts, we feel it’s helpful to highlight two main changes resulting from the latest updates.

- Spellcheck

Spell check is changed.

The setting Editor -> Behavior -> Spellcheck, is only available for US English.

However, under the next item, Editor -> Behavior -> Spellcheck languages, the user cannot select anything. Still, it is specified that Obsidian refers to the languages that are installed on MacOS. Obsidian’s behavior is different on Windows and Linux, on which OS it is possible to change the language.

On the other hand, the spell-checker intelligently skips checking what shouldn’t be controlled, such as parentheses, code blocks, links, and math blocks.

- Reading View

Afterward, we have moved on to implementing the “Live Preview” view.

With the new version, it is possible to select in the settings (always in Editor) the default view of a new panel, and you can choose between “Editing View” and “Reading View”.

With the “Reading View”, you can write and at the same time view the content as it will be with the application of markup, i.e., you see the document in the view with the formatting.

We decided to leave the Editing View because we find it more convenient to write and have the content with all the markup.

Obsidian & Pandoc: the prerequisites

To be able to use the Pandoc Plugin, you must first have installed it on your machine:

• Pandoc
• LateX

LateX

Reserving another post for LateX, we just briefly describe how to install it.

LateX is open-source and free.

LateX is a high-quality typesetting system by which you can get letterpress quality PDFs. It is well known for producing technical and scientific documentation.

To work with LateX, you need to use a specific editor (there are many open-source and free ones) through which you can set the appropriate commands and write the text that will be the content of the PDF.

To install LateX on MacOS you need to install the package called MacTex available at this page.

The MacTeX.pkg file will be downloaded to your Mac and run to install LateX.

Pandoc

We mentioned at the beginning that Obsidian integrates with Pandoc.

What is Pandoc?

Pandoc - which does not have its logo as confirmed to us by developer John MacFarlane (Professor of Philosophy at the University of California, Berkeley) - is defined “a universal document converter”.

Pandoc is a “powerful tool” to convert documents from one format to another.

For example, you can convert a document written in Markdown (with the extension .md) to a document in Microsoft Word format (with the extension .docx), or you can do the reverse.

For many file formats, it is possible a “bidirectional” conversion, i.e., they can be both converted to a specific format, and therefore, to be considered as the source (in the example above from .md to .docx, the Markdown file is the source) and as the destination (remaining on the previous case, the destination is the .docx file).

PDF, which is among the most known and commonly used file formats, can be only converted by Pandoc but as destination because it cannot be considered the source for the conversion into a file format.

On the Pandoc website, there is a very complex diagram that describes the processes of conversion from one format to another.

Moving on to the slightly more technical aspects, Pandoc is defined as a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.

To use Pandoc, even integrated into Obsidian, you must install it on your computer (Mac) if you intend to use it.

On the Pandoc installation page, you can find instructions for installation on different systems.

The installation of Pandoc on MacOS can be done in two ways:

• by downloading the installer from the official page and then launching the file with the .pkg extension;
• from the MacOS Terminal using Homebrew (we have already talked about it) with the command:

brew install pandoc

Once Pandoc is installed on the Mac, you can proceed to its integration in Obsidian.

We specify that you can also use Pandoc online by reaching this page.

If you intend to integrate Pandoc into Obsidian, the online conversion service is not the right solution.

We want to present below a video that describes - as an example - a conversion of a markdown file (extension .md) into a Microsoft Word file (extension .docx).

The command for the conversion is

pandoc pandoc_test.md -o pandoc.docx

Where the -o parameter stands for output, i.e., indicating to Pandoc what the target format should be.

Pandoc: how to configure Obsidian

To integrate Pandoc within Obsidian, you need to install a third-party plugin.

So within Obsidian, you have to click on the gear icon at the bottom of the left sidebar.

You will then have access to Obsidian’s settings and will need to select the “Community Plugins” item that is present on the left side of the settings window.

Before proceeding you have to disable safe mode, otherwise you will not be able to install third-party plugins.

At this point, by clicking on the “Browse” button that is present in the “Community Plugins” section, you will have access to a window from which you can make a textual search by typing “pandoc”.

The system will find the plugin, and it will be sufficient to click on “Install” and then on “Enable” to enable the installed plugin.

The plugin is installed, but the user must indicate the PATH to Pandoc on the machine.

We’ll have to open the Terminal app and type the command

which pandoc

Which will return the PATH where Pandoc is installed; most likely, it will be

/opt/homebrew/bin/pandoc

Remaining in the Terminal app, we type

which pdflatex

which will return the PATH where LateX is installed; most likely, it will be

/Library/TeX/texbin/pdflatex

We reaccess the settings, and after selecting the Pandoc plugin, we enter the paths as obtained above in the corresponding fields.

At this point, Obsidian is fully integrated with Pandoc. Click the key combination command + p. It will open a window, type the word “pandoc”, and see all possible options to export a document to another format from within Obsidian.

Concluding remarks

From the beginning, we have defined Obsidian as “an extraordinary app” from the beginning.

Pandoc was born from the mind and work of Prof. John MacFarlane who - by the way - is the author of the CommonMark Spec which are the specifications to make Markdown (developed in 2004 by John Gruber in collaboration with Aaron Swartz) strongly defined.

In fact, in Markdown, there are some uncertainties about the markup code that pushed John MacFarlane to define specifications to consolidate Markdown also in terms of extreme compatibility (not all applications that claim to use Markdown use the same specifications).

We’ve been using Pandoc for years and, because of its undoubted value of the efforts made by the developer, we decided to support, as sponsor, the project on GitHub.

With these implementations, Obsidian becomes an even more powerful and valid app.
By Obsidian, you can write books or voluminous publications, leaving the user the freedom to write without distraction and offering numerous supporting tools such as the graph view that describes the interactions between individual files in the vault for a global view of your work.

Follow us on Mastodon

Stay tuned!