jwogrady Work, evidence, and what I make of it
Lab note JRN 26-001done

A clean build of a website that does not exist

hugo new site produces a scaffold that builds successfully and publishes no pages at all.

Three minutes into building this site I had a perfectly clean, completely successful build of nothing at all.

Evidence

  • Ran two commands, took one screenshot of the output:

    $ hugo new site .
    $ hugo
    
                      │ EN
    ──────────────────┼────
     Pages            │  0
    
    Total in 41 ms
    $ find public -type f
    public/sitemap.xml
    public/index.xml
    public/tags/index.xml
    public/categories/index.xml
    
  • Four files. All of them machine-readable lists of the pages on my website.

  • All four describing zero pages. No actual web pages anywhere.

  • Exit code zero, forty-one milliseconds, no errors, no warnings, no complaints of any kind.

It built perfectly and published nothing.

What was going on

  • Hugo ships with no design of any kind. Not a plain one. Not an ugly default. None.
  • So it had my writing, and it had nowhere to put it.
  • A page needs a template — a reusable shell saying where the title goes, where the text goes, what wraps around it.
  • With no template, no instruction for what a page should look like, so nothing gets made.
    • And critically, the program doesn’t consider that an error.
    • You didn’t ask for anything impossible. You asked for nothing, carefully, and it gave you nothing, correctly, in forty-one milliseconds.
  • If you’re new and this happens to you, you are not being stupid. The software genuinely did report total success while producing no website, and every guide you’ll find skips this because the author was using a theme and never saw it.

What I do now

  • I stopped trusting the summary. The summary is the program telling you about itself. I want to see the thing that came out:

    $ find public -name '*.html'
    
  • That lists the actual web pages. One command.

  • It’s the only question I actually care about, and for the whole rest of the afternoon it was the thing that told me the truth while everything else was being reassuring.

The general shape

  • The export finished and the file is empty.
  • The form said “submitted” and nobody got the email.
  • The backup ran every night for eight months and backed up an empty folder.
  • CI is green and the bug is still in production.
  • Every one of those is a system reporting on its own behaviour — I did the steps I was told to do — while you assumed it was reporting on the outcome.
  • Those are two different claims and almost nothing distinguishes them for you.

“It worked” and “it produced the thing” are separate questions, and only one of them is worth asking. Go look at the output. Not the log, not the green tick, not the summary table. The output.

It built perfectly and published nothing. Three minutes in, and already the most useful thing I learned all day.