Markdown support in v2

So I’m running devel and I’m trying to set up the markdown support but I guess it’s still not complete right?

Caddyfile:

localhost:8000
markdown /

caddy run logs:

2020/02/09 22:47:39.141 INFO    using adjacent Caddyfile
run: adapting config using caddyfile: Caddyfile:2: unrecognized directive: markdown

Thanks

Instead of the markdown directive (which was not really that useful), the templates handler can render markdown: https://caddyserver.com/docs/caddyfile/directives/templates

{{markdown ...}}

https://caddyserver.com/docs/json/apps/http/servers/errors/routes/handle/templates/#markdown

1 Like

Will try, thanks!

Hi again,

So I got this caddyfile:

localhost:8000
templates
file_server browse

And a file with this content:

{{.Host}}
{{markdown "
#hey
ho 
## lets
Go
"}}

But at http://localhost:8000/test.md I just see that text and no HTML rendered. Any hint?

Make sure the content-type header is set right, the easiest way to do that is to use a proper file extension. Unfortunately there’s not enough information here to deduce if that’s actually the problem, I can only speculate.

I’m giving it a try again with v2.0.0-beta.14.

I’ve read this:

https://caddyserver.com/docs/caddyfile/directives/templates

mime are the MIME types the templates middleware will act on; any responses that do not have a qualifying Content-Type will not be evaluated as templates. Default: text/html text/plain .

So I tried this:

➜  ~/d/m/w/blog cat Caddyfile
localhost:8000
file_server
templates {
    mime .md text/markdown
}
➜  ~/d/m/w/blog cat index.md
# go
{{ .Markdown "# hey"}}
gogo

But I plain text instead of any HTML markup.

The response headers are:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 33
Etag: "q5n5ecx"
Last-Modified: Thu, 13 Feb 2020 12:59:00 GMT
Server: Caddy
Date: Thu, 13 Feb 2020 13:12:42 GMT

I also tried chaning request headers via https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj?hl=en chrome extension:

  • Accept: text/markdown
  • Content-Type: text/markdown

No luck either.

My last resort is to debug the code, but if you got something else under the hat I’m all open to ideas :slight_smile:

I think there’s a few things wrong here…

The syntax for mime subdirective is: mime <types...>, and .md is not a MIME type, so I would remove that.

Since your responses are coming back without a Content-Type header, you either need to use a supported file extension (see https://golang.org/pkg/mime/#TypeByExtension) or set the header yourself: https://caddyserver.com/docs/caddyfile/directives/header - I don’t know why changing headers via a Chrome extension would work; the Chrome extension does not run inside Caddy…

Additionally, this:

{{ .Markdown "# hey"}}

Should result in an error once the templates handler starts kicking in. The correct function as documented here is markdown not .Markdown. (Remember, this is v2, not v1.)

FWIW, here’s a better way to do Markdown in v2.

Usually, plain Markdown files are not meant to be served directly, even when rendered. In other words, you wouldn’t usually render file.md and serve its resulting HTML, because there would be no proper <!DOCTYPE>...<head>...<body> structure, and there would also be no styling or behavior!

So, I think serving Markdown directly like what you’re trying to do is not very common, because it is not very useful.

Most sites (including the Caddy site!) will serve a regular .html file as a template file, which has this action somewhere in its body:

{{markdown "..."}}

to embed the Markdown file within a proper HTML document with styling and behavior. HTML files get a proper Content-Type without needing to modify the system MIME store, so it just works, and is a lot easier and more useful than rendering Markdown directly.

If you still want to render and serve Markdown files with .md extensions directly, either:

  • rename them to use .txt (a recognized plaintext extension),
  • or add a MIME association for .md to your system,
  • or using something like header index.md Content-Type text/markdown in your Caddyfile.
2 Likes

Looking at this post and comments, I’ve been concerned.
Why are you not using Hugo and sticking to Markdown output in Caddy?

Because of simplicity: I want my whole site (home page, talks, blog posts, pictures) to be served by Caddy. No more services, dependencies, deploy strategies, compile passes, etc.

So for my (next) blog, if I can find some way to write some markdown files in a directory and have them displayed by Caddy that would be awesome.

1 Like

Cool, that’s the eventual vision.

That’s basically what we do with the Caddy docs, although we have to maintain the nav links ourselves (for now). This feature can continue to be developed over time!

1 Like

As a result, you seem to be in distress…

Hugo is developed in the same Go language as Caddy and consists of common templates. Adding pages is just adding .md files. These two go together well.

I can see his point, though; the goal of Caddy is to have fewer moving parts. Even though I agree hugo is a fine way to do it right now, it’d be better if there was a simpler, more direct way to get a simple static site up and running directly with your web server.

We are used to writing Markdown in .md files. (Eg GitHub, README.md describes really well)
There are many services corresponding to it. That may need to be considered at the Caddy level.

I’m publishing some web and blogs on Hugo, so I’m glad that Caddy recognizes the Hugo directory.
But it might be ideal for a plugin implementation.

For the record, I think hugo is great, and not complex. But it’s quick start has 7 steps with lots of customization, themes etc. Ideally I would like to do the CSS myself without any abstractions. Just render some markdown, add some CSS, profit. No compile step, no theme choosing and customization, no brew install, nothing. Yes I’m very lazy :slight_smile:

That sounds great. Not sure how you do that exactly… it’s your html file something like:

<!-- here html, head, body tags -->
{{markdown "here all the page markdown content"}}
<!-- here tags are closed -->

or

<!-- here html, head, body tags -->
{{markdown "here first markdown line"}}
{{markdown "here 2nd markdown line"}}
an so on
<!-- here tags are closed -->

Or is there a way to embed the .md file with the include func? Would be awesome to combine 2 funcs like: {{markdown include "path/to/file.md"}}

Thanks for all those great insights.

You can do it a few ways. The easiest way is your first example: {{markdown "whole Markdown file here"}}

You can also bring in a file by name: {{include "file.md" | markdown}}

Here’s another example, it’s how we serve the docs on the Caddy site: https://github.com/caddyserver/website/blob/master/src/docs/index.html

It’s a bit more advanced than the basic use case. The first 3 lines construct a filepath to the actual markdown file from the page’s URI:

{{$pathParts := splitList "/" .OriginalReq.URL.Path}}
{{$markdownFilename := default "index" (slice $pathParts 2 | join "/")}}
{{$markdownFilePath := printf "/docs/markdown/%s.md" $markdownFilename}}

(.OriginalReq is the request before rewriting, because all docs pages actually go to this index file with a directive in our Caddyfile: rewrite /docs/* /docs/index.html)

The next line splits the markdown content from its front matter (totally optional, but we wanted some data structure associated with each file for metadata purposes):

{{$markdownFile := (include $markdownFilePath | splitFrontMatter)}}

Then in the actual HTML document we can render the title, which we got from the front matter (again, this is optional):

{{$markdownFile.Meta.title}}

Then the actual rendering of the markdown file in the body of our HTML is easy:

{{markdown $markdownFile.Body}}
1 Like

2 posts were split to a new topic: File manager + hugo plugin