Working with Assets
Using CSS, JavaScript, images, and other assets with Surfgreen.
Basic usage
Surfgreen processes assets in a fairly straightforward manner: nearly everything in your contents folder will map 1:1 with where it lives on your built site. [^mapping]
[^mapping]: The only exceptions are the blocks folder within contents, and the source .md files you write: these do not carry over to your built site.
So, if you had a folder in your site called assets:
contents/assets/
It would appear on your live site at:
example.com/assets/
Folders in Surfgreen can contain anything you'd like: images, video files, whatever. They'll automatically be included in your built site.
To load an asset into your site, prepend the URL with the {{siteBase}} variable. For example, if you had an image in your assets folder, the URL you'd write in HTML would be:
{{siteBase}}/assets/my-file.jpg
CSS and JavaScript can be loaded using regular HTML tags [^common_tags] — again, using the {{siteBase}} variable.
[^common_tags]: Typically, this is <script> for JavaScript, and either <link> or <style> for CSS.
So, if you had a CSS file your assets folder, you'd add it like this:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css" href="{{siteBase}}/assets/style.css">
<!-- More HTML -->
Same goes for JavaScript:
<script src="{{siteBase}}/assets/index.js"></script>
</body>
</html>
Sass + module bundling
Surfgreen's starter kit includes support for Sass, as well as JavaScript bundling. This works via Webpack, and is pre-configured with a sensible set of defaults.
If you're using the starter kit, you can enable Webpack in your site's surfgreen.js file. Update this line of the configuration:
webpack: false,
to:
webpack: true,
You can then edit the source Sass file (scss/style.scss) and JS file (js/index.js).
Advanced Webpack usage
If you want to customize your Webpack usage — or you're building a Surfgreen site from scratch — you'll need to include a Webpack configuration file. See Webpack's documentation for more info.
Then, include it in Surfgreen in your site's surfgreen.js:
Surfgreen.start({
webpack: true,
webpackLocation: './webpack.cjs'
});
Last, but not least: previewing, building, and publishing your site.