How To Include Javascript As Hugo Theme

While Bissetii is solely a HTML and CSS Hugo theme module, it still allows Javascript usage. In fact, it freed up the Javascript for you to use from the get-go. Bissetii simplified the location for such inclusion so creators only focus on contents creation.

However, please keep in mind that Javascript will not work for Accelerated Mobile Pages (AMP) as part of its main requirement. Hence, please ensure your critical components do not depend on Javascript if AMP is enabled.

How Bissetii Loads Javascript

Javascript, especially dealing with its frameworks, usually comes in large files. This can block downloading bandwidth when they are downloaded synchonously with the main HTML and CSS body. Fortunately, modern browsers now support defer and async features and Bissetii use both of them heavily to the point of NO synchonous loading.

Version 1.13.0 and above

Bissetii loads all Javascripts in the end of the <body> sections regardless of its async and defer attributes. You still need them to manage their respective initializations.

Version 1.12.5 and Below

Bissetii loads the defer Javascripts in the <head> section while async in the end of the <body> section.

Javascript Inclusion

Depending on Bissetii version, the configuration varies accordingly.

Version v1.13.0 Onwards

Bissetii uses a single data file located in data/bissetii/assets/js.toml to organize the JS file inclusion. This is mainly to facilitate additional security features like SRI integrity checking and cross-origin ID.

Each JS file metadata and how it should be loaded is stated in each entry complying to the following pattern:

1
2
3
4
5
6
7
8
9

[0]
Algorithm = "compress"
ID = "script-myJS"            # file in 'assets/js/myJS.min.js'
URL = "/js/myJS.min.js"
Type = "application/x-javascript"
LoadMode = "defer"
CrossOrigin = "anonymous"
Integrity = "sha512-bLT0Qm9VnAYZDflyKcBaQ2gg0hSYNQrJ8RilYldYQ1FxQYoCLtUjuuRuZo+fjqhx/qtq/1itJ0C2ejDxltZVFg=="
#Content = """ """

Version v1.12.0 to v1.12.5

Bissetii relies on the 4 map table variables to configure Javascript. The file that is responsible for configuring Javascript is located in the following file:

pattern  :           data/bissetii/includes.toml
directory:     docs/.data/
repo-docs:     docs/.data/bissetii/includes.toml

Plain Javascript Inclusion

To include the JS, simply add the URL into asyncFiles or deferFiles under [includes.JS] map table.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[JS]                                      #--> vanilla HTML's Javascript assets
asyncFiles = [                            #--> just include and async-load
       # "js/myLib.js"                    #--> $assetDir/js/myLib.js
]

# ---OR---

[JS]                                      #--> vanilla HTML's Javascript assets
deferFiles = [                            #--> just include and defer-load
       # "js/myLib.js"                    #--> $assetDir/js/myLib.js
]

Asset Concatenation

To include the JS, simply add the URL into asyncAssets or deferAssets under [includes.JS] map table.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[JS]                                      #--> vanilla HTML's Javascript assets
asyncAssets = [                           #--> compile into 1 JS and async-load
       # "js/myLib.js"                    #--> $assetDir/js/myLib.js
]

# ---OR---

[JS]                                      #--> vanilla HTML's Javascript assets
deferAssets = [                           #--> compile into 1 JS and defer-load
       # "js/myLib.js"                    #--> $assetDir/js/myLib.js
]

Epilouge

Now that you know how to include external JS into your website. If you have any questions, feel free to raise them in our Issues Section.