Customise Watch Files List for Hugo Server

How to customise watch files list for hugo server to include dots files . during server mode (content development) while not compiling it as an output file in production mode?


(ref: Hestia/docs/content/en/specifications/hestiaUI/blockquote_hestiaUI at experimental · ZORALab/Hestia · GitHub)

I had successfully developed a Go-compatible string processing Hugo theme. At the moment, to use this module effectively, one has to write in a .content.html instead of the conventional _index.html. Hugo server does not watch any changes for dot files.

Current workaround is to manually nudge (e.g. write emptily in vim) the _index.html in a separate terminal when I want to render the site during development.

I attempted --poll argument but no avail.

For the reason why not to use _index.html:

  1. The module is entirely a different beast: it writes Go compatible html template file (no Hugo specific shortcode all over the places).
  2. To avoid miscommunications. Easier to document and direct customers to use Hugo and the module.
  3. It has its own processing capability that can parse Go template syntax.
  4. Prohibits users from using Hugo’s shortcode; supporting point 2.
  5. Hugo’s role is meant to only compile all the content of a given directory as it is while the theme do the data processing (theme as its own data structure parsed from hugo) and rendering.

Thanks in adv.

If you can change this to _content.html you could do this in your site configuration:

source = 'content'
target = 'content'
excludeFiles = ['**/_content.html']

The file watcher still detects changes[1] to those excluded files, but they are not transferred to public/ when you build the site.

  1. I’m not sure that if this is the expected behavior, but you can take advantage of it for now. I guess this could change at some point in the future, but there are many bigger fish to fry. ↩︎

Attempted → failed.

If you exclude the files, you will exclude them from existence for both server-mode and compilation-mode, thus even with my parser, it couldn’t find the file on the virtual FS.

Any other idea?

Do you have any problem with using _content.html instead of .content.html?

No problem. I tried a bunch of regex glob with your idea.

The new ‘problem’ is with the excludeFiles. The moment I activate it, all the excluded files did not appear on both server-mode and compilations where the new source file _content.html went missing → nothing left to read.

Judging by the design, I believe this is working as expected at least in UNIX context (mount to override).

Then as a final step in the build can’t you just remove all those files from public?

find public -type f -name "_content.html" -delete

Not scalable in distribution. I’m building a theme module for Hugo, not a specific website repository.

Between guiding user to nudge the _index.html versus distributing a bash+shell script, the former makes a lot more sense.

Then I guess you have your answer!

Noted. In that case, dated to this post, there isn’t a solution to customise the watch files list without hacking some external workarounds.

I raised a feature request on: Allow Watch Files List Customization for Hugo Server · Issue #10518 · gohugoio/hugo · GitHub

Let’s close this ticket.

Per bep’s comments in the closed issue, you can do this in site config:


render = 'never'

path = '**/_content.html'

Works on server mode but now failed on compilation mode. I tested the above in config/_default/config.toml file.


I’m not sure why the _build’s render field is not picked up mainly caused by the specific config toml files implementations (Ref: Hestia/docs/config/_default at experimental · ZORALab/Hestia · GitHub) or otherwise.

I found the necessary documentations, might take some time to figure out how things work. =(

Question: am I also expected to add front-matter in all the data files?

Solution found:

  1. You need config/_default and config/production configurations directories.
  2. Name your custom content with watchable and traceable naming prefix but not conflicting with the main bundle file (e.g. _index.html). My recommendation is using double underscore (e.g. __name.extension ).
  3. Define your usual site-level configs in the _default/config.toml (_default version).
  4. Inside your production/config.toml, only add the ignoreFiles field for extending the _default configurations. If we follow the double underscore naming prefix, the regex value should be:
ignoreFiles = [

This will let Hugo track all the underlying data files during development while not building it into output files in compilation.

Updating question because the linked reference context is actively changing. See Screenshot for the subject matter discussed:

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.