User Guide

http.markdown

markdown serves Markdown files as HTML pages on demand. You can specify whole custom templates or just the CSS and JavaScript files to be used on the pages to give them a custom look and behavior.

Syntax

markdown [basepath] { ext extensions... [css|js] file template [name] path templatedir defaultpath }

You can use the js and css arguments more than once to add more files to the default template. If you want to accept defaults, you should completely omit the curly braces.

Front Matter (Document Metadata)

Markdown files may begin with front matter, which is a specially-formatted block of metadata about the file. For example, it could describe the HTML template to use to render the file, or define the contents of the title tag. Front matter can be in YAML, TOML, or JSON formats.

TOML front matter starts and ends with +++:

+++
template = "blog"
title = "Blog Homepage"
sitename = "A Caddy site"
+++

YAML is surrounded by ---:

---
template: blog
title: Blog Homepage
sitename: A Caddy site
---

JSON is simply { and }:

{
	"template": "blog",
	"title": "Blog Homepage",
	"sitename": "A Caddy site"
}

The front matter fields "author", "copyright", "description", and "subject" will be used to create <meta> tags on the rendered pages.

Markdown Templates

Template files are just HTML files with template tags, called actions, that can insert dynamic content depending on the file being served. The variables defined in metadata can be accessed from the templates like {{.Doc.variable}} where 'variable' is the name of the variable. The variable .Doc.body holds the body of the markdown file.

Here is a simple example template (contrived):

<!DOCTYPE html>
<html>
	<head>
		<title>{{.Doc.title}}</title>
	</head>
	<body>
		Welcome to {{.Doc.sitename}}!
		<br><br>
		{{.Doc.body}}
	</body>
</html>

Along with these template actions, all the standard Caddy template actions are available to you in Markdown templates. Be sure to sanitize anything you render as HTML (use the html, js, and urlquery functions)!

Examples

Serve Markdown pages in /blog with no special formatting (assumes .md is the Markdown extension):

markdown /blog

Same as above, but with custom CSS and JS files:

markdown /blog { ext .md .txt css /css/blog.css js /js/blog.js }

With custom templates:

markdown /blog { template default.html template blog blog.html template about about.html }

Need help with this feature?

Join us in the Caddy forum, where the open source community gathers to share their knowledge.

Does your company use Caddy?

Purchase a commercial license to use Caddy with your business and for basic email support, along with other benefits!