Markdown Installed

Options

extensions string[]

File extensions to load

Default:

[ ".md", ".markdown" ]

options object

Options passed to markdown-it library

html boolean

Set true to enable HTML tags in source

Default:

true

xhtmlOut boolean

Use / to close single tags (<br />). This is only for full CommonMark compatibility.

breaks boolean

Convert \n in paragraphs into <br>

langPrefix string

CSS language prefix for fenced blocks. Can be useful for external highlighters.

linkify boolean

Autoconvert URL-like text to links

typographer boolean

Enable some language-neutral replacement + quotes beautification

quotes string string[]

Double + single quotes replacement pairs, when typographer enabled, and smartquotes on. Could be either a String or an Array. For example, you can use «»„“ for Russian, „“‚‘ for German, and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).

highlight function

Highlighter function. Should return escaped HTML, or '' if the source string is not changed and should be escaped externally. If result starts with <pre... internal wrapper is skipped.

plugins any[]

The list of markdown-it plugins to use

Default:

[markdownItAttrs, markdownItDeflist]

rules record

To modify existing rules or new custom rules

useDefaultPlugins boolean

Set false to remove the default plugins

Default:

true

Description

Markdown is a popular markup language for writing content that is converted to HTML. It is useful for pages with long text like posts, articles, or documentation sites.

Installation

This plugin is installed by default. 🎉

Configuration

If you want to change the default configuration, use the second argument of lume() function in your _config.ts file.

import lume from "lume/mod.ts";

// Markdown plugin configuration
const markdown = {};

const site = lume({}, { markdown });

export default site;

Use the options property to change the markdown-it settings:

// Change markdown-it configuration
const markdown = {
  options: {
    breaks: false,
    xhtmlOut: true,
  },
};

const site = lume({}, { markdown });

Plugins

Lume uses markdown-it as the markdown parser, with the following plugins enabled:

• markdown-it-deflist to add support for definition lists (<dl> tag).
• markdown-it-attrs to add support for CSS classes and other attributes using {}.

You can find more plugins in NPM that you can use with the plugins option. For example, to add the markdown-it-emoji plugin:

import emoji from "npm:markdown-it-emoji";

// Set the markdown plugins
const markdown = {
  plugins: [emoji],
};

const site = lume({}, { markdown });

You can pass options to your markdown-it plugins using an array with [plugin, options] signature. Example:

import anchor from "npm:markdown-it-anchor";
import footnote from "npm:markdown-it-footnote";

// Pass options to markdown-it plugins
const markdown = {
  plugins: [
    [anchor, { level: 2 }],
    footnote,
  ],
};

const site = lume({}, { markdown });

Lume markdown plugins

The repository lume_markdown_plugins contain a collection of plugins specially adapted to Lume, with useful features like extract the title from the markdown or generate a table of contents. To use these plugins, you might need to first add them to your imports map in deno.json:

{
  "imports": {
    "lume_markdown_plugins/": "https://deno.land/x/lume_markdown_plugins@v0.9.0/"
  }
}

Then in your site config file, apply them to the site:

import footnotes from "lume_markdown_plugins/footnotes.ts";

const site = lume()
  .use(footnotes());

export default site;

Last, you will need to write the code to render the extracted footnotes in your template:

{{ if footnotes.length }}
 <ul>
   {{ for note of footnotes }}
   <li id={{ note.id }}>
     {{ note.content }}
     <a href="#{{ note.refId }}" class="footnote-backref">↩</a>
   </li>
   {{ /for }}
 </ul>
{{ /if }}

You can check out the full demo for more details. In fact, each lume markdown plugin has a demo to illustrate its usage.

Creating pages in Markdown

To create a page using Markdown, just add a file with .md extension to your site. You can also add extra variables by including a front matter, a block delimited by two triple-dashed lines with YAML code:

---
title: Welcome to my page
layout: layouts/main.vto
---

# Welcome

**This is my first post** using Lume.
I hope you like it!

The Markdown code is stored in the content variable:

<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

md filter

The Markdown plugin also registers the md filter that renders any string value as Markdown and outputs an HTML fragment. The filter also accepts an argument to render the Markdown in inline mode.

<!-- Render to HTML code -->
<div>{{ text |> md }}</div>

<!-- Single line rendering, without the paragraph wrap: -->
<p>{{ text |> md(true) }}</p>