Jeff Avery ▮

Reviewing Markdown Editors

I want a markdown editor that I can use as my only editor when creating course notes (I expect to use Keynote for slides, where I want animations, multimedia etc.). It needs to be able to display rich text, code with syntax highlighting, images, and tables. Although markdown doesn’t support footnotes directly, I would appreciate that functionality.

When finished, I need to be able to export single page, or a complete document, to either PDF or HTML. The PDF should include a Table of Contents. The HTML doesn’t require a table of contents, but it should be well formatted so that I can modify it further if needed.

Finally, I want to doo this in a WYSIWYG editor. VS Code with a decent plugin can do all of this, but I really want to minimize the time spent on formatting documents. 

Overview

A/ Ulysses

The Ulysses writing application. Targets authors.

  • The filesystem is abstracted away, and you are creating documents within the application’s local storage. You need to export them to use them (or to backup as markdown). This limits the ability to do any post-processing, since you would need to export and then further modify the files.

  • Each document is created in a new “sheet”, and sheets can be reordered. You can preview an individual sheet, or a multi-document output, which is really slick. Exports to PDF, HTML, etc. 

  • Images can be dragged-and-dropped into the document and are stored in an internal library (which means that you can browse and see them on the iOS version of the app!). Images can be resized in the app, but that may or may not be respected on export, depending in the format (HTML exports with the images resized, but PDF exports full-size images).

  • There is no support for inline tables, or math.

  • There is no way to create an Index or Table of Contents! You would need to export (see first bullet above) and then use Pandoc to generate.

    Pro: sheets that can be reordered is an excellent way to handle multiple documents; exporting is excellent; iOS app is really appealing for writing on-the-go.

Con: No TOC support, and since data is contained within the app, I would need to write scripts to export the data and recreate the PDFs. No support for tables or math either. ALSO exporting is PAINFUL because you cannot even choose filenames i.e. it tries to save each file using the same filename and overwrites previous files (wtf are these guys doing??!). You would need to manually export, rename for each file, and then use a script to build them. 

B/ Typora

Typora markdown editor. In beta at this time.

  • This is a single-file editor, and its organized around opening one file per window. You can show a directory listing of files alphabetically, but each file is processed  individually. Using the underlying filesystems means that post-processing is fairly easy, since everything is stored in raw MD files. 
  • Each document is a single file. There is no preview capability so you need to export the file to see the layout. Exports to the expected formats.
  • Images can be dragged-dropped, and the source image can be copied into the source directory structure automatically. On export, it seems to struggle to export relative paths (might be fixable, need to tinker more). 
  • There is excellent support for inline tables, and math, and drawing charts and flowcharts inline. It does everything!
  • Export includes a TOC for PDF documents, but it doesn’t really matter, since it cannot export a full document from multiple files. This means that post-processing is required with Pandoc.

Pro: more features, and allows for much more customization. Handles image importing in a way that makes it easier to do post-processing.

Con: The built-in export is useless since it cannot export an entire document (i.e. handled per file). 

Comparison

Ultimately, BOTH require me to use Pandoc to produce a PDF. Typora uses native MD files so it’s simpler there (Ulysses would require me to export before generating the PDF with Pandoc). I tested both, exporting the first 3 chapters of CS 346 notes to both PDF and HTML. 

A/ Typora

1. PDF

Images weren’t exported properly (i.e. they were full size) so I had to export to HTML first (which retained the image size) and then from HTML to PDF. I wrote a makefile to cat the files, and then export x2 to accomplish this. The TOC was generated without any issues. Very clean output using the eisvogel template with Pandoc.

pandoc --template eisvogel --listing --pdf-engine=xelatex -o notes.pdf out/temp.html

markdown-review-2021-01-11.png

2a. HTML using Pandoc

Using Pandoc to convert the MD to HTML produced Unicode issues, and the images weren’t uniformly handled. Images that were rescaled in Typora (in MD) seemed to be handled best, since they had a zoom tag in the generated HTML. Full-size images were 200% the size of the window. This can be fixed by specifying the size for each image.

Produced clean HTML, but some garbled text.

markdown-review-2021-01-11-1.png

2b. HTML using Export

Exporting directly produced excellent results, although you have to export each page separately (which you would likely want anyway!)

B/ Ulyssses

1. PDF

Exporting directly from Ulysses produces a clean PDF without a TOC, so I exported the MD and used the same build script from above. Files can be exported manually, or all-selected and then exported as a single MD file (handy). 

Unfortunately images export like this. This is not valid MD, so Pandoc doesn’t recognize it (I believe it’s Markdown XL?)

However, exporting to HTML and then using Pandoc to convert to PDF, produced an identical PDF to Typora above.  markdown-review-2021-01-11-2.png

2. HTML

See above. Exporting directly to HTML produced a very clean document. CSS was split into a separate file, so modifying this would be much easier! markdown-review-2021-01-11-3.png

#markdown

January 12, 2021 ∙ software markdown writing