Embed Mastodon posts

Hugo lacks a native shortcode for Mastodon embeds. Using a custom shortcode allows you to display posts by providing a URL instead of pasting raw HTML into Markdown files. This keeps the source code clean and centralizes the embed logic in one template file.

Example

Use the following syntax in your Markdown files to display a Mastodon post.

{{< mastodon url="https://socel.net/@BGP/113805114250504687" >}}
Post by @BGP@socel.net
View on Mastodon

Arguments

The shortcode uses a single parameter to fetch and display the Mastodon post.

url
(string) The URL of the Mastodon post.

Source

Add this shortcode template to your project.

layouts/_shortcodes/mastodon.html
{{- /* Last modified: 2026-03-15T10:30:19-07:00 */}}

{{- /*
Copyright 2025 Veriphor, LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
*/}}

{{- /*
Renders the Mastodon post corresponding to the given URL.

@param {string} url The URL of the Mastodon post.

@returns {template.HTML}

@link https://docs.joinmastodon.org/methods/oembed/#get

@example {{< mastodon url="https://socel.net/@BGP/113805114250504687" >}}
*/}}

{{- with .Get "url" }}
  {{- $u := urls.Parse . }}
  {{- $qs := collections.Querify (dict "url" $u.String) }}
  {{- $api := printf "https://%s/api/oembed?%s" $u.Host $qs }}
  {{- with try (resources.GetRemote $api) }}
    {{- with .Err }}
      {{- errorf "%s" . }}
    {{- else with .Value }}
      {{- with . | transform.Unmarshal }}
        {{- .html | safeHTML }}
      {{- end }}
    {{- else }}
      {{- errorf "shortcode-mastodon" "The %q shortcode was unable to retrieve the remote data. See %s" $.Name $.Position }}
    {{- end }}
  {{- end }}
{{- else }}
  {{- errorf "The %q shortcode requires a positional parameter: the url of the post. See %s" .Name .Position }}
{{- end }}
Last modified: