diff --git a/exampleSite/content/docs/shortcodes/index.md b/exampleSite/content/docs/shortcodes/index.md
index 707deb26..b1f5654d 100644
--- a/exampleSite/content/docs/shortcodes/index.md
+++ b/exampleSite/content/docs/shortcodes/index.md
@@ -229,7 +229,7 @@ New article!
 
 ## Button
 
-`button` outputs a styled button component which can be used to highlight a primary action. It has three optional variables `href`, `target` and `rel` which can be used to specify the URL, target and relation of the link.
+`button` outputs a styled button component which can be used to highlight a primary action. It has four optional variables `pageRef`, `href`, `target` and `rel`. `pageRef` resolves an internal page reference using the current page context, producing a language- and trailing-slash-aware URL that is consistent with the theme's navigation menus. `href` accepts any URL or path. When both are set, `pageRef` takes precedence.
 
 **Example:**
 
@@ -243,6 +243,18 @@ Call to action
 Call to action
 {{< /button >}}
 
+**Example using `pageRef`:**
+
+```md
+{{</* button pageRef="docs/getting-started" */>}}
+Get started
+{{</* /button */>}}
+```
+
+{{< button pageRef="docs/getting-started" >}}
+Get started
+{{< /button >}}
+
 <br/><br/><br/>
 
 ## Carousel
diff --git a/layouts/shortcodes/button.html b/layouts/shortcodes/button.html
index c116cc11..b473d327 100644
--- a/layouts/shortcodes/button.html
+++ b/layouts/shortcodes/button.html
@@ -1,6 +1,12 @@
+{{- $href := "" -}}
+{{- with .Get "pageRef" -}}
+  {{- $href = relref $.Page . -}}
+{{- else -}}
+  {{- $href = $.Get "href" -}}
+{{- end -}}
 <a
   class="!rounded-md bg-primary-600 px-4 py-2 !text-neutral !no-underline hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
-  {{ with .Get "href" }}href="{{ . }}"{{ end }}
+  {{ with $href }}href="{{ . }}"{{ end }}
   {{ with .Get "target" }}target="{{ . }}"{{ end }}
   {{ with .Get "rel" }}rel="{{ . }}"{{ end }}
   role="button">