Compilers
Orchid includes native support for compiling Markdown, Asciidoc, Pebble, SCSS, PlantUML diagrams, and more.
Most content in Orchid comes from a file in your local filesystem. While each plugin is free to do whatever they want to generate their pages, it is common for plugins to base their internal content models around the filesystem, and as such, the content from most plugins is written in a very similar way because the content for each entry works the same.
Overview
Generally speaking, the file's extension is used to determine how a file is processed, and the compiler processing the file determines the output file extension. Here are some examples:
.md -> .html
: Markdown.peb -> .html
: Pebble.scss -> .css
: Sass, (SCSS syntax).sass -> .css
: Sass, (Sass syntax).ad -> .html
: AsciiDoc (requires OrchidAsciidoc plugin).uml -> .svg
: PlantUML (requires OrchidDiagrams plugin)
Orchid does not make a distinction between 'template' languages (like Pebble) or 'content' languages (like Markdown), As a result, the content for your pages can be written in any language you like.
Custom Output Extension
The file itself is able to override the default output extension by having a filename in a format like
filename.output.input
, such as contact.php.peb
. This tells Orchid to use the .php
extension instead of the normal
.html
extension from the Pebble compiler. The result is index.php
.
Ignored Output Extensions
There are some filenames which adhere to the above format that should not be used as the output extension. This is
common for compiled and minified CSS or Javascript, which is often named something like styles.min.css
.
You can set certain extensions to be ignored when the filename is in that format. By default, min
is already ignored,
but you may add your own ignored extensions as an array in the ignoredOutputExtensions
option in config.yml
:
# config.yml
...
services:
compilers:
ignoredOutputExtensions:
- 'min'
- 'debug'
Precompilers
Typically files are processed as a compiler of their file extension. For example, a file with the .md
extension will
be processed as Markdown.
But before it is processed as Markdown, if it has a Front Matter header, it will be precompiled as Pebble. You can use the full power of Pebble templates to add additional dynamic content to otherwise static content.
---
---
# {{ page.title }} --> # Custom Page Title
Any variables set in the Front Matter may be accessed as variables in Pebble.
---
title: Custom Page Title
foo: 'bar'
---
# {{ foo }} --> # bar
There are a number of predefined variables that are available on every page:
page
: refers to the current Page objecttheme
: refers to the theme rendering the current pagesite
: refers contains basic info about your Orchid sitedata
: all custom data loaded fromdata.yml
anddata/
files
If you need to use a Front Matter header but don't want to precompile that page, you can set precompile: false
in the
Front Matter:
---
precompile: false
---
# {{ page.title }} --> # {{ page.title }}
Alternatively, you may choose to use another language as your precompiler language of choice. This may be done
individually by a single page by setting precompileAs
to the desired language extension in its Front Matter, or for
all pages by setting the defaultPrecompilerExtension
option in your config.yml
:
---
precompileAs: 'html'
---
# {{ page.title }} --> # {{ page.title }}
# config.yml
...
services:
compilers:
defaultPrecompilerExtension: 'html'