doc22940 / panwriter

Markdown editor with pandoc integration and paginated preview.

PanWriter

PanWriter is a distraction-free markdown editor with two unique features:

1. Tight integration with pandoc for import/export to/from plenty of file formats (including HTML, docx, LaTeX and EPUB).
2. Preview pane that can show pages – including page breaks etc. Layout adjustments are done in-file using CSS, and are immediately reflected in the preview.

Download PanWriter

PanWriter is very usable, but also very much a work in progress, as there are still a few rough edges (see TODOs below). Feedback, suggestions and contributions very much welcome! Please open an issue to start a conversation.

Usage

Export preview to PDF

Select File -> 'Print / PDF' and PDF -> 'Save as PDF' in the print dialog (exact naming might depend on your OS).

This will export exactly what’s shown in the preview, and not use pandoc at all.

By adding a style field to your YAML metadata, you can change the styling of the preview and immediately see the changes. (You can later save your CSS as a theme, see Document types below.)

---
title: my document
style: |
  @page {
    size: A4;
    margin-top: 2cm;
  }
  body {
    font-size: 20px; /* set base */
  }
  h1 {
    font-size: 1.5em; /* scale relative to base */
  }
---

# my document

(To include that CSS when exporting to HTML/EPUB with pandoc, you would have to use a custom pandoc template with the snippet <style>$style$</style>. We’ll try to make this more straight-forward in the future.)

Export via pandoc

First, install the latest pandoc version, then:

Select File -> Export and choose a format.

If you have a YAML metadata block, like in the following example, PanWriter will look at the extension of the filename you chose in the dialog, and look up the corresponding key in the output YAML metadata, for example when exporting the following markdown to test.html:

---
title: my document
pdf-format: latex  # optional
output:
  html:
    katex: true  # for math output
    include-in-header:
      - foo.css
      - bar.js
  latex:
    pdf-engine: xelatex
    toc: true
    toc-depth: 3
    template: letter.tex
    metadata:
      fontsize: 12pt
  epub:
    to: epub2  # default would be epub3
---

# my document

this command will be executed:

pandoc --toc --include-in-header foo.css --include-in-header bar.js --output test.html --to html --standalone

See the pandoc user's guide for available options.

There are two exceptions to the rule that the key in the output YAML is the file extension:

1. When exporting to a .tex file, the key should be named latex.
2. When exporting to a .pdf file, the key for PanWriter to look up in the output YAML can be specified with the pdf-format key (see example above). Default is also latex, but you can also use context, html, ms, beamer, revealjs, etc. In fact, you could set it to anything, if you had a corresponding key in the output YAML with a to: field. See also Creating a PDF with pandoc.

User Data Directory

You can place certain files in the PanWriter user directory, which should be:

• macOS: /Users/your-user-name/Library/Application Support/PanWriterUserData
• Linux: ~/.config/PanWriterUserData
• Windows: C:\Users\your-user-name\AppData\Local\PanWriterUserData

If the directory does not exist, you can create it.

Default CSS and YAML

PanWriter will look for a default.css file in the user data directory, to load CSS for the preview. If that file is not found, it will use sensible defaults.

If you put a default.yaml file in the data directory, PanWriter will merge this with the YAML in your input file (to determine the command-line arguments to call pandoc with) and add the --metadata-file option. The YAML should be in the same format as above.

Document types / themes

You can e.g. put type: letter in the YAML of your input document. In that case, PanWriter will look for letter.yaml and letter.css instead of default.yaml and default.css in the user data directory.

Markdown syntax

We use markdown-it for the preview pane, which is fully CommonMark-compliant. We also added a bunch of plugins, to make the preview behave as much as pandoc as possible (including attributes, fenced_divs, definition_lists, footnotes, implicit_figures, subscript, superscript, yaml_metadata_block and tex_math_dollars). We explicitly don't support raw_html or raw_tex, since everything should be doable with the fenced_divs, bracketed_spans and raw_attribute extensions.

However, there might still be minor differences between the preview and File -> 'Print / PDF' on one hand, and File -> Export on the other.

Things we should emulate in the preview, but for which there are no markdown-it plugins yet:

• grid_tables: grid tables are the only ones in pandoc, that can have e.g. a list in a cell
• raw_attribute: we should probably just strip them from preview
• backslash at end of paragraph, e.g. ![](foo.png) \ An ugly workaround that already works is ![](foo.png)  

Pandoc markdown supports a few more things which will not render correctly in the preview, but which are not so commonly used. However, you can still use them in your markdown file, and export via pandoc will work.

Launching from the command-line

You can set up your system to launch PanWriter with:

panwriter myfile.md

On macOS, you should put the following in your ~/.bash_profile or similar:

function panwriter(){ open -a PanWriter "$@"; }

On Linux and Windows, you can make an alias to the correct location of the panwriter executable.

About CSS for print

Unfortunately, still no browser fully implements the CSS specs for paged media (paged media are e.g. print or PDF). Therefore, PanWriter's preview is powered by pagedjs – a collection of paged media polyfills by pagedmedia.org. Some background on using CSS for print:

• Motivating article on A List Apart
• Print-CSS resources, tools
• W3C Paged Media Module
• W3C Generated Content for Paged Media

Develop

Install yarn, then:

## Download source code
git clone [email protected]:mb21/panwriter.git
cd panwriter

## Install npm dependencies, PureScript compiler, etc
yarn install

## Build the PureScript project
yarn build

## To run the app in development mode:
yarn start

## To build distributable app package (goes to ./dist):
yarn dist

TODOs

• Preview:
  • respect css, header-includes, toc metadata fields
• Editor:
  • expand Format menu
  • spell check
  • improve find/replace
• add a Settings/Preferences window (or should this just be a settings.yaml file?) where you can:
  • set a CodeMirror editor theme css
  • edit the default CSS and YAML files
  • choose pandoc executable (probably with file-open dialog, which we can use for app sandboxing with security-scoped bookmarks)
• Write pandoc lua filter that does some PanWriter-specific transformations:
  • add page-break syntax
  • Variable substitution in body
  • read out style metadata and inject into header-includes
  • read out type metadata and if it references a css file, put the path into the css metadata variable
• GUI popup on file import: at least allow to set -f, -t, --track-changes and --extract-media pandoc options.
• Unify PanWriter custom document type and pandoc template concepts?
• Rename type metadata key to doctype?

Powered by

PanWriter is powered by (amongst other open source libraries):

• pandoc (import/export)
• Electron (app framework)
• CodeMirror (editor)
• For the preview pane:
  • pagedjs
  • markdown-it
  • KaTeX