Let’s be honest: you’re not here to watch your entire site rebuild from scratch every time you fix a typo. You want speed. You want to see your change, and only your change, reflected instantly. That’s the dream, and Hugo’s --navigateToChanged flag is the closest you’ll get to a direct portal to that dream. It’s not magic, but it’s such a clever piece of engineering that it feels like it.

Here’s the deal. When you run hugo server --navigateToChanged, Hugo does something radically different from a standard server. It doesn’t just build everything and wait. Instead, it builds the entire site once (so it has a baseline), fires up the server, and then goes into a hyper-vigilant watch mode. The moment you save a file, it doesn’t just blindly rebuild the world. It performs a surgical strike.

How It Actually Works (The Clever Bit)

Hugo’s compiler is frighteningly smart. It maintains a detailed dependency graph of your entire site. It knows that post/my-blog-post.md uses the template layouts/_default/single.html, which in turn pulls in a partial layouts/partials/header.html, and that all of these are styled by assets/sass/main.scss.

So, when you change layouts/partials/header.html, Hugo’s intelligence agency kicks into gear. It cross-references the change against its graph and says, “Aha! This partial is used on 247 pages. I need to rebuild those 247 pages and only those 247 pages.” It then does exactly that. This is the core of its speed. The --navigateToChanged flag takes this a glorious step further: once that targeted rebuild is complete, it automatically instructs your browser to navigate to the page you were just looking at and reload it.

Think about that. You’re staring at http://localhost:1313/blog/my-great-post/. You edit a partial. You hit save. In your terminal, you see a blur of activity that lasts milliseconds, not seconds. Then, before you can even reach for your mouse to hit refresh, your browser does it for you. The feedback loop is almost instantaneous.

Using It Like a Pro

The command is simple, but the effect is profound.

hugo server --navigateToChanged

That’s it. There’s no secret handshake. Now, go to your browser, navigate to any page on your local site, and start editing. The key thing to remember is that it will navigate to the exact URL you are currently on in your browser. This is brilliant for working on a specific page or post.

But what if you’re working on something site-wide, like a header partial? You don’t care about the specific page; you want to see the change everywhere. This is where a bit of cunning comes in. Open two browser windows. Keep one on the homepage as your “canary” to see the global change, and use the --navigateToChanged window to work on the specific page where you’re testing functionality. It’s a cheap and effective multi-monitor setup for your brain.

The Inevitable Rough Edges

This is a fantastic tool, but it’s not clairvoyant. There are limits to its graph, and you need to know them.

  1. Asset Pipeline Changes: If you’re using Hugo Pipes (e.g., to compile SCSS or JS), the rebuild behavior can be different. Changing an assets/sass/main.scss file will correctly rebuild the CSS, but the browser navigation might happen before the CSS is fully written to disk. You might need a manual refresh. It’s usually fast enough that it works, but don’t be shocked if it hiccups.
  2. The Home Page is a Black Hole: Be cautious if you’re actively viewing the home page (/) when a change happens. The home page can often list every single recent post, making it a dependency nightmare. A change to a single post might force a rebuild of the home page and the post itself. It’s still faster than a full rebuild, but it’s the slowest possible scenario for this flag.
  3. It’s Not a Panacea for Bad Structure: If you’ve built a Rube Goldberg machine of nested partials and where statements that query your entire site collection, Hugo’s graph might deem more pages dependent on a change than you intuitively expect. The tool is brilliant, but it can’t save you from a convoluted theme.

The bottom line? Use --navigateToChanged by default. It is, without a doubt, the fastest way to iterate in development. It turns Hugo from a “fast static site generator” into a “live-updating dynamic-feeling powerhouse.” It’s the kind of feature that, once you get used to it, makes working with any other generator feel like you’re wading through treacle.