Writing daily with hugo-cms.nvim keeps a few things on hand. A short SEO checklist before publishing, the publishing loop, and a few places where it’s easy to trip.

SEO Check Before Publishing

Before I flip :Hugo draft from true to false, I run through:

  • title, descriptive and scannable, under ~60 characters
  • description as the meta description, 120–160 characters, benefit-focused
  • slug set per language on multilingual posts, URL-safe, lowercase, hyphens
  • cover.image and cover.alt, with alt text matching the language
  • At least one tag and one category, if the site uses taxonomies
  • Internal links via {{< ref >}} or {{< relref >}}, because Hugo validates them at build time and broken refs break the build
  • alt on every image, not just the cover

The plugin helps with a lot of these. Reminding myself is on me.

My Publishing Loop

The typical sequence from start to published post:

  1. :Hugo new or :Hugo resume, then write.
  2. :Hugo preview for hugo server with the browser on the current page, rebuilding on every change.
  3. Run through the SEO check, fix things if needed.
  4. :Hugo draft flips the flag, across all language files at once.
  5. :Hugo publish for build and deployment.

Gotchas

A few things that caught me out early on.

:help hugo-cms comes up empty at first. lazy.nvim with cmd = "Hugo" keeps the plugin out of runtimepath until you invoke :Hugo once. Run any :Hugo command, or :Lazy load hugo-cms.nvim, and :help works after that.

Buffer open, front-matter edited. When a buffer is open and modified, hugo-cms.nvim writes its front-matter change into the buffer, not directly to disk. Vim’s “file changed externally” dialog doesn’t fire. Save when you’re done.

Terminal split separator. The splits used by :Hugo preview and :Hugo publish use a winbar for the visual separator and status line. With laststatus=3 you get a clear boundary between editor and terminal. Without winbar the global statusline would swallow it.

Truncated paths in :Hugo open. The picker’s path column is capped, long slugs get truncated with …. What’s after the ellipsis isn’t fuzzy-matchable. Search for what you can see, or adjust PATH_COL_CAP in commands/open.lua if you regularly need more path visible.

Showing shortcode syntax inside a post. If you want to show {{< ref >}} or any other shortcode literally in your Markdown, putting it in backticks is not enough. Hugo evaluates shortcodes inside inline code too and breaks the build with “invalid number of arguments”. Use the escape syntax {{< ... >}} (the plugin adds it automatically when you use :Hugo media insert shortcode).