hugo-theme-relearn/docs/content/configuration/customization/extending/_index.en.md

+++
categories = ["explanation", "howto"]
description = "Add further code to your site"
options = ["relearn.dependencies"]
title = "Adding Scripts"
weight = 2
+++

A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.

## Adding JavaScript or Stylesheets to All Pages

### Simple Solution

Previous documentation of Hugo recommended adding `css/custom.css` and/or `js/custom.js` to your `static` or `assets` directory. This is supported by the theme.

To gain more flexibility, see the [next section](#flexible-solution) below.

### Flexible Solution

To add CSS stylesheets, JavaScript files or any other addition to the `<head>` of every page, you can include them in `layouts/partials/custom-header.html` or `layouts/partials/custom-footer.html`.

However, this can make your site larger than necessary if these files are only needed on a few pages. The next section explains how to add dependencies only when needed.

This way of customization will discard the mechanism for the [simple solution](#simple-solution) above. You will have to add code for inclusion of `css/custom.css` and/or `js/custom.js` yourself if you still need this.

## Custom Shortcodes with Dependencies

Some shortcodes need extra JavaScript and CSS files. The theme only loads these when the shortcode is used. You can use this for your own shortcodes too.

For example, to create a shortcode called `myshortcode` that needs the `jquery` library:

1. Create the shortcode file `layouts/shortcodes/myshortcode.html` and add the folloging line somewhere:

    ````go {title="layouts/shortcodes/myshortcode.html"}
    ...
    {{- .Page.Store.Set "hasMyShortcode" true }}
    ...
    ````

2. {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Add this to your `hugo.toml`:

    {{< multiconfig file=hugo >}}
    [params.relearn.dependencies]
      [params.relearn.dependencies.myshortcode]
        name = 'MyShortcode'
    {{< /multiconfig >}}

3. Create loader file `layouts/partials/dependencies/myshortcode.html`:

    ````go {title="layouts/partials/dependencies/myshortcode.html"}
    {{- if eq .location "footer" }}
      <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
    {{- end }}
    ````

Important notes:

- Character casing is relevant!
- The `name` in `hugo.toml` must match the `Store` key used in the shortcode file, prefixed with a `has`.
- The key of `relearn.dependencies` must match the loader file name.

See the `math`, `mermaid`, and `openapi` shortcodes for examples.

{{% notice note %}}
For advanced customization, you can use the dependency loader in your own partials:

````go
{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}
````
{{% /notice %}}

Give a unique name for the `location` parameter when you call it, so you can distinguish your loaders behavior depending on the location it was called from.
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00			`+++`
docs: add categories taxonomy #567 2024-10-12 19:28:28 +02:00			`categories = ["explanation", "howto"]`
docs: moving imageeffects #567 and other stuff 2024-10-06 17:31:29 +02:00			`description = "Add further code to your site"`
docs: marking config options #567 2024-10-06 20:37:18 +02:00			`options = ["relearn.dependencies"]`
theme: add compat way of including scripts #1009 Open 2025-02-02 14:00:21 +01:00			`title = "Adding Scripts"`
docs: moving imageeffects #567 and other stuff 2024-10-06 17:31:29 +02:00			`weight = 2`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00			`+++`

docs: review #567 2024-10-07 15:30:53 +02:00			`A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.`
docs: moving imageeffects #567 and other stuff 2024-10-06 17:31:29 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			`## Adding JavaScript or Stylesheets to All Pages`
docs: moving imageeffects #567 and other stuff 2024-10-06 17:31:29 +02:00
theme: add compat way of including scripts #1009 Open 2025-02-02 14:00:21 +01:00			`### Simple Solution`

			Previous documentation of Hugo recommended adding `css/custom.css` and/or `js/custom.js` to your `static` or `assets` directory. This is supported by the theme.

			`To gain more flexibility, see the [next section](#flexible-solution) below.`

			`### Flexible Solution`

			To add CSS stylesheets, JavaScript files or any other addition to the `<head>` of every page, you can include them in `layouts/partials/custom-header.html` or `layouts/partials/custom-footer.html`.
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			`However, this can make your site larger than necessary if these files are only needed on a few pages. The next section explains how to add dependencies only when needed.`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
theme: add compat way of including scripts #1009 Open 2025-02-02 14:00:21 +01:00			This way of customization will discard the mechanism for the [simple solution](#simple-solution) above. You will have to add code for inclusion of `css/custom.css` and/or `js/custom.js` yourself if you still need this.

docs: review #567 2024-10-07 15:30:53 +02:00			`## Custom Shortcodes with Dependencies`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			`Some shortcodes need extra JavaScript and CSS files. The theme only loads these when the shortcode is used. You can use this for your own shortcodes too.`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			For example, to create a shortcode called `myshortcode` that needs the `jquery` library:
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			1. Create the shortcode file `layouts/shortcodes/myshortcode.html` and add the folloging line somewhere:
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
			````go {title="layouts/shortcodes/myshortcode.html"}
docs: review #567 2024-10-07 15:30:53 +02:00			`...`
			`{{- .Page.Store.Set "hasMyShortcode" true }}`
			`...`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00			````

docs: review #567 2024-10-07 15:30:53 +02:00			2. {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} Add this to your `hugo.toml`:
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
			`{{< multiconfig file=hugo >}}`
			`[params.relearn.dependencies]`
			`[params.relearn.dependencies.myshortcode]`
docs: chapter 3 content-complete #567 add other stuff 2024-10-12 18:37:59 +02:00			`name = 'MyShortcode'`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00			`{{< /multiconfig >}}`

docs: review #567 2024-10-07 15:30:53 +02:00			3. Create loader file `layouts/partials/dependencies/myshortcode.html`:
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
			````go {title="layouts/partials/dependencies/myshortcode.html"}
			`{{- if eq .location "footer" }}`
			`<script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>`
			`{{- end }}`
			````

docs: review #567 2024-10-07 15:30:53 +02:00			`Important notes:`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			`- Character casing is relevant!`
			- The `name` in `hugo.toml` must match the `Store` key used in the shortcode file, prefixed with a `has`.
			- The key of `relearn.dependencies` must match the loader file name.
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
docs: review #567 2024-10-07 15:30:53 +02:00			See the `math`, `mermaid`, and `openapi` shortcodes for examples.
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
			`{{% notice note %}}`
docs: review #567 2024-10-07 15:30:53 +02:00			`For advanced customization, you can use the dependency loader in your own partials:`
docs: first draft chapter 2 #567 2024-09-29 23:48:56 +02:00
			````go
			`{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}`
			````
			`{{% /notice %}}`
docs: review #567 2024-10-07 15:30:53 +02:00
			Give a unique name for the `location` parameter when you call it, so you can distinguish your loaders behavior depending on the location it was called from.