Using hugo to render my Zettelkasten folder

I have a folder ~/dox/notes full of .md files. I want to render them all with Hugo.
First of all, i created a folder ~/dox/notes/test with config.toml file (and the rest files created by hugo new site), containing:

baseURL = 'http://localhost:12000/'
languageCode = 'en-us'
title = 'Zettelkasten'

And if i try to run
hugo --contentDir ~/dox/notes --configDir ~/dox/notes/test serve --port 12000, the server says Page not found on any page including the /.
But that seems to be caused by the following issue, so later on that.

I copied all the markdowns to the contents/ folder just to be sure, and the same thing happened.
I googled a bit and found that i need to create layouts/_default/single.html file. So i created it and put {{ .Content }}

in there, and then my file appeared on http://localhost:12000/ as expected. But then i noticed that the links are incorrect, being in form of [foo]( in source, and also having .md extension in rendered hrefs, which is not how Hugo names pages. Another bit (a chunk) of googling led me to layout/_default/_markup/ containing <a href="{{ replace .Destination ".md" "" | safeURL }}">{{ .Text | safeHTML }}</a>, which is hacky but at least it works (for rewriting links at least).
But then when i tried to go to the links they all have Page not found error. And google says that it is the way Hugo works, rendering content/ as http://localhost:12000/foo/.

And yes, it does output warnings:

WARN 2023/03/07 17:41:40 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts
 Lookup Rules for this combination.
WARN 2023/03/07 17:41:40 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Lay
outs Lookup Rules for this combination.
WARN 2023/03/07 17:41:40 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Lay
outs Lookup Rules for this combination.

And the info:

  Pages            | 188
  Paginator pages  |   0
  Non-page files   |   0
  Static files     |   0
  Processed images |   0
  Aliases          |   0
  Sitemaps         |   1
  Cleaned          |   0

I’m too confused and tired by now. Can someone explain me what should i do if i just want to simply render every markdown file in specified folder (recursively), with links in form of [foo]( or [bar](../, without any fancy templating or index page or taxonomy pages or yaml front matter nonsense?
And the general advice and tips on running a portable ZK of markdown files (meaning a folder that does not have anything about Hugo in it and preferably not even located in a Hugo project, but i can fix that with Docker if the --contentDir flag wouldn’t work) with Hugo would also be nice.

A complete example of one of your markdown files would be helpful.


The content/ folder is in the shape i have my ZK folder.

Things to note:

  • Files in subfolders (diary/) actually contain links without the ../. That is in part of because of:
  • I have my own tag convention of form #[tag](, to tag notes with notes basically, and it has to be short while still standard markdown
  • So every link preferably should be just the name of file. I can move the zettels from diary/ folder to the root and have every note in there if necessary, though.
  • I have images in images/ subfolder and referencing them using ![image](images/name.png). I know that Hugo uses totally different folder for static files, so a solution for that would be nice (although i can just mount them to static with Docker if necessary).


  • Command that i run: hugo serve --noHTTPCache --buildDrafts --port 12000 --disableFastRender .

OK, thanks. I’ll have a look at this later today; I think I’ve done something similar.

Looking at your content and file naming convention, we would have to run a script against your files to create a temporary directory, then run Hugo to build a navigable site. If that is acceptable, we can continue…

Depending on the script. If it would work transparently (i can just work with files in the folder and it would live reload them) then it’s fine.
Are you talking about shell script, or Hugo script?

That would be more difficult, but not impossible. We would need something like incron to watch the original files, and trigger conversion upon new/change.


In this case, does the destination (, a page-relative link) resolve to actual file?

But what exactly is the problem with Hugo just rendering the files as they are? Looks to me like it should, no?

The problem with scripting it may be that it can get in the way of using different Hugo features like backlinks, TOC etc. Don’t know, though, maybe not.

At the end I want to use Hugo in part because it can do nice things too.

Yes, but not always. I tag files with such links, and then if certain link gets used a certain amount of times i create the actual file and write something to it. Or just “# A subject index/tag note” and a parent tags in it.

No, it won’t.

I found something that I had put together a few years ago for a similar situation. I’ll get you a repo you can clone and test later today. It won’t have the live update capability, but that’s something that could be added later.

git clone --single-branch -b hugo-forum-topic-43346 hugo-forum-topic-43346
cd hugo-forum-topic-43346

Then read the README file.