Markdown Installed

Create pages in Markdown format

Options See on deno.land

extensions string[]

The list of extensions this plugin applies to

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

keepDefaultPlugins boolean

Set true append your plugins to the defaults

Default:

false

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.

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 });

Additionally, you can use hooks to add additional plugins and rules.

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],
  keepDefaultPlugins: true,
};

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

The keepDefaultPlugins option keeps the two default plugins installed by default by Lume (markdown-it-deflist and markdown-it-attrs). Set it to false (or don't set it at all) to replace the defaults with your specified plugins.

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],
  keepDefaultPlugins: true,
};

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.

Hooks

This plugin exposes the following hooks:

addMarkdownItPlugin(plugin, options) To add additional plugins.
addMarkdownItRule(name, rule) To add additional rules.

import lume from "lume/mod.ts";
import anchor from "npm:markdown-it-anchor";
import footnote from "npm:markdown-it-footnote";

const site = lume();

site.hooks.addMarkdownItPlugin(anchor, { level: 2 });
site.hooks.addMarkdownItPlugin(footnote);

export default site;

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.njk
---

# 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 | safe }}
  </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 | safe }}</div>

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