The Kit Language
A .kit file is HTML with special comments.
Kit adds two things to HTML: imports and variables.
CodeKit compiles .kit files into regular HTML files.
You can import any file, of any type, into a Kit file. The syntax is just like the syntax for importing files in CSS:
<!-- @import "someFile.kit" --> <!-- @import "file.html" -->
The syntax is super-flexible too. You can use
@include instead of
@import if you prefer and quotes and spaces are totally optional (except for the space after the @import keyword; that one you need). All of the following are valid:
<!-- @include someFile.kit --> <!-- @import '../../someFileAtRelativePath.html' --> <!--@include no_spaces_at_beginning_or_end.txt-->
When you save the Kit file, CodeKit simply replaces this special comment with the entire text of the file you're importing. If the imported file is also a Kit file, CodeKit will go compile it first, allowing you to chain multiple files together and build modularly.
The file extension is optional. If you don't provide it, CodeKit will automatically add the ".kit" extension when it looks for the file. (Note: an extension IS required to import other file types, such as HTML or PHP files.)
You may import more than one file at a time by using a comma-separated list. Each one's contents will be inserted into the compiled HTML in the same order as the import list. Example:
<!-- @import someFile, otherFile.html, ../thirdFile.kit -->
Kit follows the "partial" convention from Sass. Whenever you have a file that is ONLY meant to be imported into others, you can add a leading underscore to the filename. (This helps you quickly recognize these "import-only" files in the Finder.) You do NOT, however, need to worry about including the underscore in the
To understand how CodeKit resolves import statements, suppose we have a file named "master.kit" that has this special comment in it:
<!-- @include someFile -->. CodeKit will follow this sequence to resolve the import:
Don't worry about screwing up. CodeKit will not let you create infinite import loops between files and will provide really helpful error messages, including line numbers and file names (even within imported files).
You can declare and use string variables in any Kit file. Here's an example of how we declare them:
<!-- $myVar = This text is amazing --> <!-- $width = 40px -->
Then, at any point after these declarations, we can use these variables like this:
<body> <p> <!--$myVar--> </p> <div style="width: <!--$width-->;"> Stuff </div> </body>
When CodeKit compiles the Kit file, it will replace these special comments with the value of the variables. The original "variable declaration" comments will not appear in the HTML output.
Depending on which languages you already use, you've probably got a favorite syntax. Good news: Kit supports all of them. You can use either
@ to indicate a variable name and you can use equals signs, colons or just a space to assign a value. All of the following are valid variable declarations:
<!--$myVar:This text is amazing--> <!--@var2=Some other incredible text--> <!-- @width = 40px --> <!-- $manifesto Who needs colons and equals signs? -->
All Kit variables are simple text strings. This means you can NOT do stuff like add variables together, etc. (If you need that ability, it's time to step up to PHP, Jade, Slim or Haml.) Also, everything after the variable name is considered part of the variable value. So, if you wrap your text in quotation marks, the quotation marks will show up when you use the variable later on. Leading and trailing whitespace in the variable value, however, is ignored.
You may only declare or use a SINGLE variable per special comment. Attempting to declare or use multiple variables in a single comment will result in undefined behavior and may tear the space-time continuum.
Any variable you declare is available to use at any later point. This extends into imported files. If you declare a variable in "master.kit" and then import "beta.kit", the variable from "master" will be available in "beta" as long as long as it was declared before the
<!--@import beta.kit--> statement. By contrast, any variables declared in "beta.kit" will NOT be available in "master.kit".
Just take any HTML file and rename it to *.kit instead of *.html. Then, add your project to CodeKit if it's not already there.
You can use Kit for more than just HTML. If you've got a PHP file, just rename it to *.kit and then, in CodeKit, right-click that file and choose "Set Output Path". In the dialog that pops up, tell CodeKit to name the output file *.php instead of *.html. Now, when you save this .kit file, CodeKit will create a PHP file! You can do this with literally any language.
To change the extension on an HTML file in the Finder, you have to right-click it, choose "Get Info" and change the extension in that window. If you try to do it in the Finder window itself, Finder will actually rename the file to "*.kit.html" instead of changing the extension to .kit.
Lots of people have asked me to do "imports for HTML files". They don't want to deal with PHP just to do simple things like including a navigation bar on every page without coding it a dozen times. That's the very specific problem Kit is designed to solve.
I went back and forth on this. I spoke to lots of web developers. The answer is pretty simple: once you add these special comments to a file, that file is not really HTML any more. I mean, you could open it in a browser and it would display, but you'd be missing all the included content and anything that relied on variables.
Plus, if you have "index.html" with special comments, that file needs to compile into... "index.html". So there's a name collision. What do we do? Maybe stick a "-ck" suffix on the output file? That's dumb, because the browser will load "index.html", not "index-ck.html". Maybe we stick a suffix on the source file! So the one with the special comments becomes "index-dev.html" and the output file gets "index.html". Well that's just bloody confusing.
Other tools solve this problem by duplicating your entire website into a "build" folder. But that's dumb, because most modern sites have hundreds if not thousands of files and duplicating everything wastes time and space.
CodeKit elegantly solves this problem by assigning these files a new extension and treating them just like any other language that the app supports.
Negative, ghostrider. The Kit specification is open source and any developer is welcome to use that code to integrate Kit support into any product. I want to be crystal clear on this: The Kit language is NOT an attempt to tie people to CodeKit. It's simply the best way I know to fulfill a really common feature request. I want folks to use my app because it's the greatest damn tool on the planet, not because they're forced to use it. And if you think for once second that I'm about to rely on crappy lock-in techniques to make people use my app, just wait until you see what 2013 brings to CodeKit. I haven't even gotten warmed up yet.