This post is more of a continuously updated note on possible workflows that are based on plain text and the principles of minimal computing.

Plain text and MarkDown

AcademicMarkdown

CriticMarkup

CriticMarkup: extension to MMD for editorial markup of texts. The project website is http://criticmarkup.com/ and the code is hosted on GitHub

• Integration into tools:
  • Sublime Text 3’s AcademicMarkdown package supports syntax highlighting for CriticMarkup
  • There is a CriticMarkup SL3 package. It is not managed by package control and a documentation can be found here
  • The CriticMarkup toolkit contains processors for various programs but not for Sublime Text.
  • Integration of CriticMarkup and Pandoc
• Basic Syntax
  • Addition {++ ++}
  • Deletion {-- --}
  • Substitution {~~ ~> ~~}
  • Comment {>> <<}
  • Highlight {== ==}{>> <<}

KramDown

An extension of MarkDown with a strict, unambiguous syntax used in Jekyll. The documentation of the syntax can be found here.

Pandoc and Jekyll

Pandoc can be used as standard processor for markdown in jekyll with the help of small plugins. However, one cannot use any plug-ins if jekyll is run on GitHub-pages, which operate in safe-mode. There was a lengthy discussion on the jekyll forum whether or not to include pandoc as a markdown processor. Unfortunately this has been rejected by the jekyll team.

The advantage of pandoc as markdown processor would be support for image captions etc.

Another pandoc plugin for jekyll

jekyll-pandoc

To install it via terminal type

$ gem install jekyll-pandoc

It can then be referenced in one’s site’s _config.yml as markdown: pandoc after the following has been added:

gems: 
    - jekyll-pandoc

jekyll-pandoc-plugin

This was originally designed to work with jekyll 1.x. Some forks have been updated to provide compatibility with jekyll 2.x and 3.x

Git / GitHub

• Chad Black’s getting started with github and prose.io on using a combination of GitHub, jekyll, and prose.io for a collaborative seminar blog.
• GitHub, Academia, and Collaborative Writing
• Push, Pull, Fork: GitHub for Academics
• GitHub for Academics: the open-source way to host, create and curate knowledge
• Living in a Plain Text World (Tools We Use)
• This software for academic paper writing is inspired by Git
• How To: Use Git to Version Your Writing
• Using git in my writing workflow

Jekyll

• Tags in Jekyll / GitHub pages
  • Tags in jekyll
  • How To Use Tags And Categories On GitHub Pages Without Plugins
• Pandoc
  • Another pandoc plugin for jekyll
• Jekyll themes
  • Poole, Jekyll’s buttler: editor for Jekyll themes, at the moment at least two themes are available and GO::DH Minimal Computing SIG used it to build its website
• Plug-ins: if hosted on GitHub, jekyll runs in safe mode and disables third-party plug-ins
  • Jekyll-hook
• add image captions:
  • with an include tag

Liquid templating

Liquid templating was designed by and for the shopify website: “Liquid is an open-source, Ruby-based template language created by Shopify. It is the backbone of Shopify themes and is used to load dynamic content on storefronts.”

• Liquid template engine
• Great overview of syntax and commands
• Jekyll Date Formatting Examples using liquid

Images in Jekyll

the standard markdown syntax of ![caption, alt text](path to image file) works with jekyll, but the alt text is not written to a caption element etc.

A comment on stackoverflow suggests to generate a new template file called image.html in _includes

<figure class="image ">
    <a href="">
        <img src="" alt="">
        <figcaption></figcaption>
    </a>
</figure>

and then to call this template with

![My cat, Robert Downey Jr.](/assets/my-cat.jpg)

The regex to replace existing markdown image links with the new liquid ones is:

1. find: !\[(Page.+)\]\(\{\{site.baseurl\}\}(/assets/.+.png)\)
2. replace>

Post preview in jekyll

add excerpt_separator: <!--more--> to _config.yml or the YAML block of your individual post.