If you maintain a HubSpot CMS theme, custom module, or blog template that has been live for a few years, there is a good chance it contains HubL that is quietly out of date. Your pages may render perfectly today, yet the code behind them relies on filters and functions that HubSpot has already replaced with cleaner, faster alternatives.

The good news is that the list is short, the replacements are clear, and most migrations take minutes per file. This guide walks through every deprecated HubL filter and function, shows the old and new syntax side by side, and gives you a safe process to update your codebase without breaking a single page.

What Does “Deprecated” Mean in HubL?

A deprecated filter or function is one that HubSpot has replaced with a newer, more streamlined and optimized version. According to the official HubSpot developer documentation, deprecated items still operate as intended, so nothing breaks overnight. However, HubSpot encourages using the current HubL functions for all new and future projects.

 

In simple words: deprecated does not mean broken. It means “stop using this in new code, and plan to replace it in existing code.”

Why You Should Not Ignore Deprecated Filters

Because the old syntax still works, it is easy to postpone the cleanup. Here is why it is worth doing now rather than later:

  • Future-proofing: deprecated code is the first candidate for removal or unsupported behavior over time.
  • Cleaner, consistent code: one modern API across your whole theme makes onboarding new developers far easier.
  • Better maintainability: replacements such as content_by_id() unify several older, single-purpose functions.
  • Optimized output: newer functions such as require_css() and require_js() are the recommended way to load assets.
  • Client confidence: agencies delivering themes or marketplace modules look more professional with up-to-date code.

Quick Reference: Deprecated vs Replacement

Bookmark this table. It covers every deprecated HubL filter and function listed in HubSpot’s documentation.

Type Deprecated Use Instead
Filter datetimeformat format_datetime
Filter format_currency format_currency_value
Function blog_post_by_id() content_by_id()
Function page_by_id() content_by_id()
Function blog_topics() blog_tags() (renamed)
Function blog_recent_topic_posts() blog_recent_tag_posts() (renamed)
Function datetimeformat() format_datetime()
Function get_public_template_url() get_asset_url()
Function include_css() require_css()
Function include_javascript() require_js()

Deprecated Filters (with Code Examples)

HubSpot currently lists two deprecated filters. Both deal with formatting, and both are very common in blog listing and pricing templates.

1. datetimeformat → format_datetime

Used everywhere to display publish dates, update dates, and event times. It accepts a format pattern, and optionally a timezone and a locale.

DEPRECATED

{{ content.updated|datetimeformat("%B %e, %Y") }}
{{ content.publish_date|datetimeformat("%B %e, %Y %l %p") }}
{{ content.publish_date|datetimeformat("%B %e, %Y %l %p", "America/Los_Angeles") }}
{{ content.publish_date|datetimeformat("%B %e, %Y %l %p", "America/Los_Angeles", "es-US") }}

RECOMMENDED

{{ content.updated|format_datetime("%B %e, %Y") }}
{{ content.publish_date|format_datetime("%B %e, %Y %l %p") }}

Tip: after swapping the filter name, always check the output on a staging page. Review the format_datetime entry in the HubL filters reference for the exact pattern, timezone and locale options it supports.

2. format_currency → format_currency_value

Used to display prices in the right currency format for each locale, for example product pages, pricing tables and donation forms.
DEPRECATED

{% set price = 100 %}
{{ price|format_currency("en-US") }}
{{ price|format_currency("fr-FR") }}
{{ price|format_currency("jp-JP", "JPY", true) }}

RECOMMENDED
Switch to format_currency_value, and confirm its argument order in the official filters reference before replacing every instance.

{% set price = 100 %}
{{ price|format_currency_value(...) }}

Deprecated Functions (with Code Examples)

Eight functions are on the deprecated list. They fall into three groups: content lookups, blog helpers and asset loaders.

 

Content lookups: blog_post_by_id() and page_by_id()

Both are replaced by a single, unified function: content_by_id().
DEPRECATED

{% set my_post = blog_post_by_id(4715624297) %}
{% set my_page = page_by_id(4715624297) %}

RECOMMENDED

{% set my_content = content_by_id(4715624297) %}
<a href="{{ my_content.absolute_url }}">{{ my_content.title }}</a>

Blog helpers: blog_topics() and blog_recent_topic_posts()

HubSpot renamed “topics” to “tags”, and these two functions were renamed to match.
DEPRECATED

{% set my_tags = blog_topics("default", 250) %}
{{ blog_recent_topic_posts("default", "culture", 5) }}

RECOMMENDED

{% set my_tags = blog_tags("default", 250) %}
{{ blog_recent_tag_posts("default", "culture", 5) }}

Date helper: datetimeformat() (function form)

DEPRECATED

{{ datetimeformat(content.publish_date_local_time, "%B %e, %Y") }}

RECOMMENDED

{{ format_datetime(content.publish_date_local_time, "%B %e, %Y") }}

Asset loaders: get_public_template_url(), include_css(), include_javascript()

These are the three you will most often find in older themes and legacy modules.
RECOMMENDED

{{ get_public_template_url("custom/page/my-theme/script.js") }}
{{ include_css("custom/page/my-theme/styles.css") }}
{{ include_javascript("custom/page/my-theme/script.js") }}

RECOMMENDED

{{ get_asset_url("../js/script.js") }}
{{ require_css(get_asset_url("../css/styles.css")) }}
{{ require_js(get_asset_url("../js/script.js")) }}
Good to know: in module files, require_css() and require_js() are generally used alongside get_asset_url() to reference theme assets by relative path. Always test the final asset URL in the page source after migrating.

Learn more about our HubSpot themes and modules.

How to Find Deprecated Code in Your Theme

Before changing anything, find out where the old syntax lives. If you work locally with the HubSpot CLI, download your theme and search the whole folder.

 

# Search across your local theme folder
grep -rnE "datetimeformat|format_currency\(|blog_post_by_id|page_by_id|blog_topics|blog_recent_topic_posts|get_public_template_url|include_css|include_javascript" ./my-theme

In VS Code, the same search works with the global search panel and regex mode switched on. Do not forget these commonly missed locations:

 

  • Blog listing and blog post templates (dates and tags)
  • Custom modules: module.html files, including marketplace modules
  • Global partials: headers, footers, and sidebars
  • Email templates that format dates or currency
  • Third-party or child themes that you inherited from a previous developer

Step-by-Step Migration Process

Step 1: Audit

Search every template, module and partial. List each file and the deprecated item inside it.

Step 2: Back Up

Clone the theme or use version history so you can roll back instantly if needed.

Step 3: Replace

Swap one deprecated item at a time using the quick reference table above.

Step 4: Test

Preview on staging: dates, currencies, tag lists, CSS and JS loading, and related posts.

Step 5: Publish

Push changes live, then monitor pages and the browser console for errors.

Step 6: Document

Note what changed in your README so the next developer is never surprised.
Start with the lowest-risk replacements, the straight renames such as blog_topics() to blog_tags() and datetimeformat to format_datetime. Handle asset loaders last, since a wrong path can break styling or scripts on every page that uses the module.

 

Best Practices to Stay Future-Proof

  • Check the HubSpot developer changelog and deprecation pages a few times a year.
  • Build new modules only with current HubL functions, never copy-paste from old forum answers without checking.
  • Use a staging portal or a sandbox for every template change.
  • Keep your theme in Git and manage it through the HubSpot CLI for clean, reviewable changes.
  • Add a short “HubL audit” to your regular maintenance checklist for client sites.
  • Review marketplace and third-party modules before installing; outdated code is a hidden maintenance cost.

Final Thoughts

Deprecated HubL filters and functions are not an emergency, but they are a clear signal. Replacing datetimeformat, format_currency, include_css and the rest takes little effort today, and it keeps your HubSpot website clean, consistent and ready for whatever comes next.

If your site runs on a large theme, many custom modules, or inherited code you are not sure about, a structured audit saves hours of guesswork and prevents costly mistakes on live pages.

 

FAQs

What does deprecated mean in HubL?
A deprecated filter or function has been replaced by a newer, more optimized one. It still works today, but HubSpot recommends using the current alternative for all new and future projects.
Will my website break if I keep using deprecated HubL?
Not right now. HubSpot documents these items as still operating as intended. Even so, it is safest to migrate so your code does not depend on features that are being phased out.
Which filter replaces datetimeformat?
Use format_datetime, both as a filter and as a function. The function form is format_datetime().
What replaces include_css() and include_javascript()?
Use require_css() and require_js(), usually together with get_asset_url() to reference your theme files.
Should I use page_by_id() or blog_post_by_id() anymore?
No. Both are replaced by content_by_id(), which works for pages and blog posts through a single function.
How do I find deprecated code across my whole theme?
Download your theme with the HubSpot CLI and run a project-wide search for the deprecated names. Also check custom modules, partials and email templates.

Related HubSpot Resources

Need Help Updating Your HubSpot Theme?

We audit HubSpot CMS themes and modules, replace deprecated HubL safely, and keep your site fast, clean and future-ready.

Pin It on Pinterest

Share This