Squarkdown comes with sensible defaults out-of-the-box, but you’ll almost certainly want to configure it to suit your need.
Squarkdown reads in your configuration from 1 of 4 places:
/squarkup.toml/squarkup.json/.squarkdown/squarkup.toml/.squarkdown/squarkup.json
TOML is the recommended format. JSON support is in progress!
IMPORTANT
You need a squarkup config file – even if empty – to run Squarkdown, otherwise Squarkdown can’t find your project root!
Categories
Configuration options are neatly organised into categories. Throughout the docs you’ll see them referred to as category.option, e.g. format.preserve-comments.
| Category | Description |
|---|---|
errors | Error handling |
project | Project metadata |
paths | Where Squarkdown should find files |
out | Output |
format | Markdown rendering |
assets | Assets preprocessing |
fonts | Fonts preprocessing |
TIP
If you’re new to Squarkdown,
paths.siteis the most important option to set.From there,
errorsandpathsare the most important categories to start with.
Errors
| Option | Type | Values | Default |
|---|---|---|---|
strict | boolean | true | |
debug | boolean | true | |
on-error | string | warn kill | warn |
file-already-exists | string | overwrite error skip | overwrite |
link-broken | string | mark-invalid strip-extension link-to-github error | strip-extension |
strict
Enable stricter safety checks?
This includes:
- Requiring
dest(ination) to be explicitly provided in the charm squark - Validating charm squark only contains [Squarkdown-native fields]
- Checking directories remain under your project root
- Checking multiple files don’t export to the same directory
debug
Enable more helpful debug output?
This includes:
- When a rendering error occurs, showing a snapshot of the source text pointing out the exact error
This requires Squarkdown to do more work, so has a tiny impact on performance. It’s enabled by default since the performance impact is usually negligible, and it makes error messages significantly better!
New in v4.2.
on-error
How should Squarkdown react to non-fatal errors?
Defaults to warn, meaning Squarkdown will report the error but continue processing. This means one bad page won’t bring down the entire squarkup, and you’d be able to catch more errors in a single run.
In production, you’ll probably want kill, so that you don’t get an incomplete build.
file-already-exists
How should Squarkdown react when a file to render to already exists?
Defaults to overwrite, meaning Squarkdown will overwrite the existing file.
In production, you may want error to avoid Squarkdown overwriting a handwritten +page.svx without you knowing.
link-broken
How should Squarkdown handle a .md link that does not resolve to an active file?
This can happen because either:
- The link is totally broken: the linked
.mdfile doesn’t exist at all! - The link would be broken: the linked file doesn’t have
#SQUARK live!, so wouldn’t have a page in the site.
Project
| Option | Type |
|---|---|
name | string |
github | string |
name
New in v4.2.
github
New in v4.2.
Paths
| Option | Type | Default |
|---|---|---|
site | string | your project root |
sources | string array | your entire project repo |
include | string array | .md files |
exclude | string array | .git/, .node_modules/, .svelte-kit/ folders |
site
sources
include
exclude
Out
| Option | Type | Notes | Default |
|---|---|---|---|
folder | string | path relative to project root | src/routes/ in your site folder |
site-data-path | string none | path relative to site | none |
render-page-ts | boolean | true | |
shorter-fields | boolean | false |
folder
site-data-path
render-page-ts
shorter-fields
Format
| Option | Type | Default |
|---|---|---|
inject-head | boolean | true |
preserve-heading | boolean | false |
preserve-comments | boolean | false |
externalise-links | boolean | true |
inject-head
New in v4.2.
preserve-heading
preserve-comments
externalise-links
Assets
| Option | Type | Notes | Default |
|---|---|---|---|
folder | string | path relative to project root | your project root |
site-assets-folder | string none | path relative to project root | none |
extensions | string array | .png, .jpg, .jpeg, .webp, .svg files |
folder
site-assets-folder
extensions
Fonts
| Option | Type | Values |
|---|---|---|
queries | string array |