If you like my work, please consider supporting its development.

Add the following to your site’s config.toml file:

[params.background]
    src = "images/background_lg.png"
    #medium_src = "images/background_med.png"
    #small_src = "images/background_sm.png"
    fit = "auto"
    fixed = true
    tile = false
params:
    background:
        src: images/background_lg.png
        #medium_src: images/background_med.png
        #small_src: images/background_sm.png
        fixed: true
        fit: auto
        tile: false
{
    "params": {
        "background": {
            "src": "images/background_lg.png",
            "medium_src": "images/background_med.png",
            "small_src": "images/background_sm.png",
            "fixed": true,
            "fit": "auto",
            "tile": false
        }
    }
}

Image Sources

Change src to the relative path from the site’s assets folder where the background image can be found. In the above example, the file would be found at {site root}/assets/images/background.png.

If the file is hosted on another website, use that image’s URL instead.

Optionally set medium_src and small_src to smaller images to use on screens that are at most 1024px and 640px, respectively. If either of these are omitted, the next largest image source will be used.

Image Fit

Set fit to "contain" if you want the behavior of CSS background-size: contain, and "cover" if you want the behavior of background-size: cover, and anything else to not stretch the image at all. Setting it to “auto” uses the default behavior of background-size: auto;.

If the image is not stretched and does not cover the entire background, the page_background color will be visible behind the image.

Tiled Image

If tile is set to true, the image will be tiled horizontally and vertically. If false, the image will not be tiled at all.

Users wanting more advanced control can set tile to any valid value for the background-repeat CSS property.

Fixed Image

If fixed is true, the image will not scroll with the page; the page will look it is sliding across the image. Set to false to make the image scroll with the page.