Orchid accumulates assets from multiple sources before they are added to the page, including themes, plugins, components, and Front Matter.
Orchid accumulates assets from multiple sources before they are added to the page as <script>
and <style>
tags. In
particular, assets can be contributed to a page from:
On anything that adds assets to the Page, you can also define additional assets to be added alongside them. This is
added as the extraCss
or extraJs
properties of the theme config in config.yml
, a page's Front Matter, or in a
component's config.
These assets take an arbitrary path to a resource, and will automatically compile it according to its file extension and render it in the final site for you.
Extra Assets attached to a Theme
# config.yml
theme:
extraCss:
- 'assets/css/custom.scss'
extraJs:
- 'assets/js/custom.js'
Extra Assets attached to a Page
# pages/page-one.md
extraCss:
- 'assets/css/custom.scss'
extraJs:
- 'assets/js/custom.js'
Extra Assets attached to a Component in an Archetype
# config.yml
allPages:
components:
- type: 'pageContent'
extraCss:
- 'assets/css/custom.scss'
extraJs:
- 'assets/js/custom.js'
For assets that are not attached to a page, such as images or downloadable files, you must tell Orchid which folders you
want copied over. By default, any file assets/media/
will be copied over directly if it is a binary file format (such
as image files or PDFs), or compiled if it is a known file type (such as SCSS). You can configure additional directories
in your config.yml
.
# config.yml
assets:
sourceDirs:
- 'assets/media'
- 'assets/overrides/css'
- 'assets/overrides/js'
If a file is not being copied over correctly, you may need to tell Orchid that it should be treated as a binary file
stream instead of a character stream. You can set in your config.yml
which file extensions should be treated as binary
content. The following file extensions are considered binary by default: jpg
, jpeg
, png
, pdf
, gif
, svg
,
otf
, eot
, ttf
, woff
, woff2
# config.yml
services:
compilers:
binaryExtensions:
- 'jpeg'
Orchid includes basic support for media management, including simple image manipulation. You can use the asset()
template function to load an asset, and Orchid will make sure it ends up in your final site.
# Any page or template
{{ 'assets/image.jpg'|asset }}
Rotate an image asset. Rotation angle is expressed in degrees.
# Any page or template
{{ 'assets/image.jpg'|asset|rotate(90) }}
Scale an image asset by a constant factor.
# Any page or template
{{ 'assets/image.jpg'|asset|scale(0.85) }}
Resize an image asset to specific dimensions. By default, image is resized maintaining its aspect ratio, and is reduced
to the largest image that can fit entirely within the specified dimensions. Use the mode
parameter to resize the
image to exactly the specified dimensions, or crop it to a specified edge.
# Any page or template
{{ 'assets/image.jpg'|asset|resize(800, 600, "exact") }}
As assets are transformed, they automatically get renamed to ensure unique asset files are generated. However, you may
wish to rename them youself, which can be done with the rename()
filter, which accepts the standard permalink
formatting string as an argument. If you provide a file extension in the permalink which does not match the original
resource, it will be reformatted into the target file format if it is a valid image format.
# Any page or template
{{ 'assets/image.jpg'|asset|rename("assets/media/hero.png") }}
Multiple transformations may be applied to a single asset. Simply use more than one of the above filters. You can use the same filter more than once, and they will be applied in turn from left-to-right. Assets are not rendered until the end of the entire pipeline; intermediate assets are not created for each filter.
# Any page or template
{{ 'assets/image.jpg'|asset|resize(800, 600, "exact")|rotate(45)|rotate(45) }}
Orchid takes care of rendering favicons for you. If you do not provide one yourself, it will use the default Orchid
logo. If you have your own favicon you'd like to use, simply drop it in your resources root named favicon.ico
and
Orchid will use that one instead.