Knit, without
the mystery.

Declarations stay CSS.

The basic form is !{property:value}. Put multiple properties in one declaration or split them into multiple declarations when that improves readability.

<button class="!{color:white;background:black;padding:10px 20px;border-radius:6px} !:hover{background:gray}">
 Button
</button>

For global and base element styles, KnitCSS recommends using vanilla CSS in a standard stylesheet or style tag. Use KnitCSS for styles that are closely coupled to the markup they belong to.

Use normal selectors.

Put a CSS selector after !. Pseudo-classes and normal combinators can be used directly.

<button class="!{opacity:1} !:hover{opacity:.8} !:active{opacity:.6}">
 Button
</button>

KnitCSS supports complex selectors, but styling each element directly keeps your code easier to read, change, and maintain.

Responsive without a new language.

Direct at-rules such as !@media(...), !@supports(...) and !@container(...) are supported when they contain declarations.

<div class="!{display:block} !@media(min-width:768px){display:grid}">...</div>

<div class="!@supports(display:grid){display:grid}">...</div>

<div class="!@container(min-width:400px){font-size:20px}">...</div>

Recommended breakpoint syntax

The default config created by knitcss --init includes a custom at directive. Use its named cases for a shared responsive vocabulary.

<div class="!{display:block} !at(medium){display:grid}">...</div>

<div class="!at(small-only){display:block}">...</div>

[directive.at]
at-rule[base-only]="@media(max-width:319px)"
at-rule[xx-small]="@media(min-width:320px)"
at-rule[xx-small-only]="@media(min-width:320px) and (max-width:479px)"
at-rule[x-small]="@media(min-width:480px)"
at-rule[x-small-only]="@media(min-width:480px) and (max-width:639px)"
at-rule[small]="@media(min-width:640px)"
at-rule[small-only]="@media(min-width:640px) and (max-width:767px)"
at-rule[medium]="@media(min-width:768px)"
at-rule[medium-only]="@media(min-width:768px) and (max-width:1023px)"
at-rule[large]="@media(min-width:1024px)"
at-rule[large-only]="@media(min-width:1024px) and (max-width:1279px)"
at-rule[x-large]="@media(min-width:1280px)"
at-rule[x-large-only]="@media(min-width:1280px) and (max-width:1535px)"
at-rule[xx-large]="@media(min-width:1536px)"

At-rule plus selector

With a raw at-rule, put & between the at-rule and selector. The default at directive does not require that separator.

<button class="!@media(min-width:768px)&:hover{color:red}">Button</button>

<button class="!at(medium):hover{color:red}">Button</button>

Native nesting still works.

Inside a declaration block, & has its normal CSS nesting meaning. Separate Knit declarations are often shorter, but nesting remains available when it reads better.

<button class="!{
 color:black;

 &:hover{
 color:red;
 }
}">
 Button
</button>

KnitCSS supports CSS nesting, but keeping declarations separate makes your code easier to read, change, and maintain.

Name it. Copy it.

Knit includes two built-ins: id gives a declaration a reusable name, and copy reuses one or more named declarations.

<div class="!id(card){padding:20px;border-radius:8px}">
 First card
</div>

<div class="!copy(card){background:white}">
 Second card
</div>

Local properties override copied ones. IDs may contain letters, numbers, hyphens and underscores; each ID must be unique in the template.

Multiple IDs

<div class="!copy(layout,surface,text){padding:24px}">...</div>

Copied declarations are combined in listed order, then the local declaration is applied.

Partial copy

<div class="!copy(card.declaration){background:black}">...</div>

Add project vocabulary.

Custom directives live in knitcss.ini. A directive can contribute an at-rule, selector or CSS declarations, and can have named or argument-count cases.

At-rule directive

[directive.at]
at-rule[medium] = "@media(min-width:768px)"
at-rule[medium-only] = "@media(min-width:768px) and (max-width:1023px)"

<div class="!at(medium){display:grid}">...</div>

Selector directive

[directive.state]
selector[hover] = ":hover"
selector[focus] = ":focus"

<button class="!state(hover){color:red}">Button</button>

Declaration directive

[directive.stack]
declaration = "display:flex;flex-direction:column"

<div class="!stack{gap:10px}">...</div>

Directive arguments

A numeric case matches the number of arguments. Use \1, \2, \3 and so on inside the configured action.

[directive.range]
at-rule[2] = "@media(min-width:\1) and (max-width:\2)"

<div class="!range(640px,1024px){display:grid}">...</div>

Explicit project wiring.

Configuration is organized into INI sections. Strings can use single or double quotes, booleans are unquoted, lists use [], and named entries use bracket keys.

[knit]
in_directory = "src"
out_directory = "dist"
css_file = "public/knit.css"
cache_file = "dist/.knitcss"
exclude_paths[] = "vendor","generated"
signal_file = "dist/.changed"
signal_content = "KNIT_TIME\nKNIT_PATHS"

Replacements

The [replacements] section performs simple text replacements in compiled templates. 1790928721 is also available as a built-in replacement.

[replacements]
ASSET_ROOT = "/assets"
API_VERSION = "v2"

<img src="ASSET_ROOT/logo.svg">

Tell Knit where syntax is legal.

Boundaries limit where Knit syntax is scanned. In this example, for HTML templates, a class-attribute boundary keeps Knit from interpreting unrelated text elsewhere in the file.

[boundaries]
class[] = '\sclass\s[0:]=\s[0:]"', '"'

[template.html]
extensions[] = ".html"
boundaries[] = "class"

Boundary matchers

Templates

Template sections are named [template.<name>]. They choose file extensions, active boundaries and whitespace behavior. Full suffixes such as .blade.php are supported.

[template.markup]
extensions[] = ".html", ".blade.php"
boundaries[] = "class"
optimize_whitespaces = true
keep_indentation = true
keep_new_lines = true

Set optimize_whitespaces = false when you want Knit to leave template formatting unchanged.

Child templates

A boundary region can be delegated to another configured template, for example, a script region inside an HTML template.

[template.html]
templates[script] = "javascript"

templates[script][] = "javascript", "embedded"

An empty child template templates[<boundary>] = '' is treated as a comment and stripped away.

A small, complete toolbelt.

Running knitcss without options compiles once using knitcss.ini from the current working directory.

Logging fields

path, time, count, filesystem and task can be requested with --log.

--init, --reset, --version and --help are separate commands; only one of those command flags is used at a time.