Rendering README.md in a file_server block

[Kise]

Hello,

I have simple caddy server that are serving some repositories content

:80 {
        root * /opt/repos
        file_server {
                hide *.log *.logs .*
                browse
        }
}

I was wondering if there a way to render README.md like in gitlab or github

for example,

/opts/repos/rr1/

• file1
• file 2
• README.md

when browsing and README.md is found is it possible to render the content in page?

[matt (Matt Holt)]

Yes it is! I’m mobile ATM but I’ll reply with an answer soon.

[Kise]

Thank you for your fast reply. Looking forward for it,

[matt (Matt Holt)]

The basic idea is you can render markdown as HTML using templates:

templates

Then you’ll need a templated file that runs the {{markdown}} action. You can see how we render our Markdown docs as HTML in our own GitHub repo:

caddyserver/website/blob/master/src/docs/index.html

That might be a little more advanced than what you need. But the basic idea is there. You’ll also need to rewrite requests to your .md files to go to your template file so they can render the requested Markdown file instead.

---

Optional:

You can also treat your README filenames as “index” files:

file_server {
    index README.md index.html
    ...
}

for example. That will prevent directory listings when a README.md file is present, if you want to just show the readme instead. But that’s optional.

---

I’d be open to discussing ways to make this easier, but we did something like this in v1 with a markdown directive. The problem is that Markdown files, by themselves, aren’t generally useful for display as part of a website. There’s no styles or JS, there’s no header, footer, or nav. It’s just a plain-looking, bare-bones HTML document. Maybe that’s fine, but we found most people needed the ability to put markdown within something like a template.

And templates allow you to preface your Markdown with front matter, which can be used in the template as variables/values!

[Kise]

Hi, Thanks for the ideas. what i want is really something similar to Gitlab/github where the readme is included with the index directory.

i am almost sure it’s possible with the template you gave i’ll have to give it a try, sorry for the late reply as i am on vacation right now =)

Edit:

{{- define "icon"}} {{- if .IsDir}} {{- if .IsSymlink}}

so far this seems to work as requested.

Thank you

[matt (Matt Holt)]

Ohh I see. Yes that should do then! glad you figured it out and thanks for sharing!