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* }

  • basepath is the base path to match. Markdown will not activate if the request URL is not prefixed with this path. Default is site root.
  • extensions… is a space-delimited list of file extensions to treat as Markdown (defaults to .md, .markdown, and .mdown); this is different from the ext directive which assumes a missing file extension.
  • css indicates that the next argument is a CSS file to use on the page.
  • js indicates that the next argument is a JavaScript file to include on the page.
  • file is the JS or CSS file to add to the page.
  • template defines a template with the given name to be at the given path. To specify the default template, omit name. Markdown files can choose a template by using the name in its front matter.
  • templatedir sets the default path with the given defaultpath to be used when listing templates.

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 +++:

  1. +++
  2. template = "blog"
  3. title = "Blog Homepage"
  4. sitename = "A Caddy site"
  5. +++

YAML is surrounded by ---:

  1. ---
  2. template: blog
  3. title: Blog Homepage
  4. sitename: A Caddy site
  5. ---

JSON is simply { and }:

  1. {
  2.     "template": "blog",
  3.     "title": "Blog Homepage",
  4.     "sitename": "A Caddy site"
  5. }

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):

  1. <!DOCTYPE html>
  2. <html>
  3.     <head>
  4.         <title>{{.Doc.title}}</title>
  5.     </head>
  6.     <body>
  7.         Welcome to {{.Doc.sitename}}!
  8.         <br><br>
  9.         {{.Doc.body}}
  10.     </body>
  11. </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!