Liquid Markdown

Posted : admin | On 30-04-2021



20 Jan 2021

I use Jekyll for most of my static sites. I recently discovered Netlify and Netlify CMS and found them delightful. As part of a recent launch, I decided to incorporate Netlify CMS into the project.

I found it easy to add Netlify CMS to Jekyll and decided to customize the admin experience. I moved several pieces of information into data files and configured Netlify CMS to edit these data pieces.

Editable data:

Typora is one of the most popular Markdown editors, and for good reason. Liquid is an open-source template language created by Shopify and written in Ruby. It is the backbone of Shopify themes and is used to load dynamic content on storefronts. Liquid has been in production use at Shopify since 2006 and is now used by many other hosted web applications.

  • Categories
  • Header/footer/legal links
  • Authors (in separate files)
  • Articles (_posts)
  • Pages (any other .markdown page)

The way that Netlify CMS presents these in the UI can be a bit clunky. I found it an acceptable compromise.

To present the Jekyll page as accurately as possible in the CMS preview pane, I created several preview components and made some adjustments to the CMS index page.

Jekyll Configuration

Modifications to the _config.yml file:

I exclude the admin site from the sitemap and also add a global configuration for Author page templates.

Netlify CMS

This is what our admin/index.html currently looks like:

A breakdown of the tools that we use in our rendering process:

  • react
  • html-react-parser
  • liquidjs
  • markdown-it
  • markdown-it-attrs

We configure Netlify CMS with a JavaScript file instead of using the YML file for Content-Security-Policy reasons.

That configuration file looks like this:

We had to make a few adjustments to the regular post in order to match it up perfectly with Jekyll.

One of those changes involved updating the defaults for the date format:

Note the changed format, 'YYYY-MM-DD HH:mm ZZ', which corresponds with the way Jekyll writes date strings in our configuration.

Preview Templates

The file admin/preview-templates/index.js contains the good stuff:

This will preprocess Liquid tags in your Jekyll Markdown and then run it through a Markdown parser that correctly handles attributes.

The default widget renderer would yield this:

Not a big deal, right? It’s still hideous. So I set out to fix it.

This particular example also handles pullquotes. We’re using a slightly modded version of the Octopress pullquote tag.

If you have any questions, feel free to reach out to me on Twitter on @torgnybjers!

Related posts

A realistic implementation of various Markdown specifications as a flexible, drop-in alternative for language-gfm. Adds smart context-aware behavior to lists, and keyboard shortcuts for inline emphasis and links/images.

Installation

  1. Install language-markdown via either
  • your terminal: apm install language-markdown
  • the Atom GUI: Atom > Settings > Install > Search for language-markdown
  1. Select language-markdown as your Markdown grammar. Open a Markdown file and
  • press ctrl+shift+L and choose 'Markdown'
  • choose 'Markdown' from the grammar selection interface in the bottom right-hand corner of the window

To avoid conflicts this package tries to disable the core package language-gfm. If you run into any issue, make sure you've selected the correct grammar.

Supported grammars

  • CommonMark Markdown
  • Github Flavored Markdown (including AtomDoc)
  • Markdown Extra
  • CriticMark annotation
  • Front Matter (yaml, toml and json)
  • R Markdown

Additional features

Liquid Markdown
  • Smarter lists
    • Automatically create new list-items when pressing enter
    • Indent or outdent list-items by pressing tab or shift+tab
    • Toggle tasks with cmd+shift+x or ctrl+shift+x
    • Remove empty trailing list-items when pressing enter
  • Add shortcuts (via _, * and ~) for toggling inline-emphasis and strike-through on selected text
  • Add shortcuts for converting selected text to a link (via @) or an image (via !)
  • Supports embedded HTML- and Liquid-tags
  • Embedded math functions (via language-latex and language-mathematica)

Syntax-theme support

By default, most syntax-themes only provide basic styling for .markup classes. This package provides additional, more specific classes which are supported by the following syntax-themes:

  • minimal-syntax (light, high-contrast)
  • minimal-syntax-dark (dark, high-contrast)
  • pen-paper-coffee (light, low-contrast)
  • pubster-syntax (dark, high-contrast)
  • one-o-eight-syntax (various, medium-contrast)
  • east-end-syntax (light, medium-contrast)
  • east-end-notebook-syntax (light/lined, medium-contrast)

If you are interested in adding support for all .markup classes to your syntax-theme, take a look at the relevant section in the contribution guide.

F.A.Q.

If you run into any issues, consult the F.A.Q. first. Amongst other things, this document contains information about common issues involving:

Liquid Markdown For Loop

  • spell-check
  • autocompletion
  • syntax-highlighting
  • whitespace

Contributing

Liquid Header Markdown

If you want to contribute to this package, have a look at the contribution guide.