Documentation for deprecated functions, methods, etc

I’d like to bring up some concerns about the documentation for deprecated functions, methods etc.

I observed that whenever a feature/method is deprecated, it’s removed from the documentation. This can be a problem for some people.

For example, .Site.IsServer is deprecated in Hugo v0.120.0. What if someone not using v0.120.0, needs to know about .Site.IsServer ?

Instead of removing .Site.IsServer from documentation, would it be possible to relocate it to a dedicated page, perhaps docs/content/en/
This page could serve as a list of all deprecated features, including their respective documentation.

Put simply, I believe that a dedicated page like this would effectively convey the information:
(building upon on Joe’s list)

  1. Don’t use Thing One anymore
  2. Use Thing Two instead
  3. We’re going to remove Thing One at some point in the future
  4. Thing One’s documentation (with a note that it (is/is going to be) deprecated in favor of Thing Two.

Additionally, deprecated stuffs can be denoted with a special marker just like how new features are denoted (see the screenshot below). Perhaps something along the lines of ‘Marked as deprecated in v0.120.0’ in a striking red color.


The dedicated page is unnecessary since I doubt anyone new to Hugo would be interested in knowing what old features it had in the past. Seeing the deprecation warnings in the terminal is better since I would think a majority of Hugo users use CLI anyway.

Plus with how fast Hugo features change, that would be unmaintainable in the long run.

You are right. Someone new to Hugo may not be interested.

What about existing themes, sites that still use the deprecated feature?

That’s where this support forum comes in handy for users.

My take on this…

Let’s wait and see if the recent documentation removals cause a problem. When we deprecated URL on Page in favor of RelPermalink/Permalink, I can’t recall any documentation requests for the deprecated method.

But again, let’s wait and see. I am somewhat resistant to adding a page or creating “deprecated” markers simply due to the maintenance required.

1 Like

At least kind enough to attach some information on PRs or Issues on GitHub which adding breaking changes, about what is the solution or update devs need to follow. Thanks

The release notes do contain that information. The problem is that many devs with Hugo themes don’t keep up with the releases (by being busy or other reasons), unless something breaks and is reported by users.

Recently, Bep even added a few issues showing changes in upcoming versions that may also contain breaking changes. MIni issue tracker for Hugo 0.121.0 · Issue #11549 · gohugoio/hugo · GitHub

1 Like

The problem referenced above was a self-inflicted wound, not a breaking change.

1 Like


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