WARNING
This page is outdated as of Squarkdown v4.0, which rewrites Squarkdown in Rust. Bear with me while I bring it up to date!
The charm squark is an extended squark which should go under the # h1 title of a page. It provides all the metadata and instructions for how Squarkdown should squarkup the page.
When Squarkdown processes files, it will only export them if they indicate they are active and provide necessary metadata. This takes the form of an expanded squark known as the charm squark, which looks like this:
<!-- #SQUARK live!
| dest = path/to/destination
| capt = This is a charm squark!
| ...
-->Overview
TIP
Place the charm squark at the start of the text, below the title if you prefer. The sooner Squarkdown can find it, the more time saved – across a large repo, it adds up!
The charm squark is broken over multiple lines. After #SQUARK comes a series of Flags. These tell Squarkdown, Hey, keep this in mind!
Below are the Fields, neatly arranged with pipe signs and equals, which can be set to desired values. Squarkdown processes and stores these internally for processing and rendering.
So the overall format is:
<!-- #SQUARK live! <flag>
| <field> = <value>
-->Precise details of the available flags and fields are covered below.
Flags
| Flag | Description | Notes |
|---|---|---|
live! | File is active. | If this flag is not detected within a few lines, the file is assumed to be inactive and processing is skipped – this saves a lot of otherwise wasted time! |
dead! | File is inactive. | Little difference to omitting core entirely, but explicitly indicates to developers “we’re not squarking this up, for a reason”. |
Anything else that follows the format <identifier>! and appears in this first line will be parsed as a flag and saved in FileData.flags.
Fields
For fields which accept multiple values, these should be separated with /.
| Option | Parameters | Values | Description | Default | Notes |
|---|---|---|---|---|---|
dest | <path> | any | Where the file will be exported to. | Relative to site routes (<path/to/site>/src/routes) | |
title | <title> | any | Title injected into <head> of the exported HTML within <title>. | head. | Different to head. |
desc | <description> | any | Description injected into <head> of the exported HTML within <meta name="description"> | capt if provided. | Different to capt. |
head | <head> | any | Displayed <h1> text in the page header. | First detected # text in the Markdown file. | Different to title. |
capt | <caption> | any | Short caption text displayed below the header. | A description of what the page is (such as “Yu-Gi-Oh! Archetype”) rather than a unique concrete description – different to desc. | |
style | <style(s)> | stylesheets | Stylesheets to apply. | Base stylesheet. | Should be a list of file names without file extensions. |
duality | <duality> | light dark light! dark! | Default colour theme to use if user has no preference. | light | User preference can be ignored by following it with a !. |
index | <index(s)> | any | Where to index the page. | ||
date | <year> / <month/season?> / <day?> | <season>: spring summer autumn winter | Creation or publish date of the page. | Used as a sort parameter when searching. | |
clean | <clean-aspect(s)> | line-breaks comments braces angles | Aspects of the text to cleanup. |
Example
Here’s what a Markdown file with a full charm squark would look like:
# Example: Never Gonna Give You Up
<!-- #SQUARK live!
| destination = rick/roll
| title = Happy April Fools
| description = Definitely not a rickroll
| heading = Never Gonna Give You Up
| caption = Rick Astley
| index = soundtracks
| release-date = 1984 April 1
| clean = line-breaks / comments
-->Cheatsheet
And for reference, here’s a quick cheatsheet for all the flags and fields:
<!-- #SQUARK live! <flag> ...
| dest = <destination-directory>
| title = <webpage-title>
| desc = <webpage-description>
| head = <page-header>
| capt = <page-caption>
| style = <stylesheet> / <stylesheet> ...
| index = <index> / <index> ...
| tags = <tag> / <tag> / ...
| date = <year> <month/season?> <date?>
| clean = ... / ...
-->