-
Notifications
You must be signed in to change notification settings - Fork 6
Home
A *.kit file is HTML with special comments. Kit adds two things to HTML: imports and variables. CodeKit compiles Kit files into HTML, so the Kit language is great for building static sites.
You can import any file, of Any type, into a Kit file. The syntax is just like CSS:
<!-- @import "someFile.kit" -->
<!-- @import "file.html" -->
The syntax is flexible. You can use @include instead of @import if you prefer. Quotes and spaces are totally optional (except for the space after the @import statement; 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 process it first, allowing you to chain multiple files together.
The file extension is optional. If you exclude it, CodeKit will automatically add the ".kit" extension when it looks for the file. 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 "import-only" files in the Finder.) You do NOT, however, need to include the underscore in any @import statements.
To understand how CodeKit resolves import statements, suppose we have a file named "master.kit" that has this special comment: <!-- @include someFile -->. CodeKit will follow this sequence to resolve the import:
- Look for "someFile.kit" in the same folder as "master.kit"
- If that fails, look for "_someFile.kit" in the same folder
- If that fails, look for "someFile.kit" in all CodeKit Framework folders
- If that fails, look for "_someFile.kit" in all CodeKit Framework folders
- Don't worry about screwing up. CodeKit will not let you create infinite import loops between files and provides helpful error messages, including line numbers.
You can declare and use string variables in any Kit file. Here's how we declare them:
<!-- $myVar = This text is amazing -->
<!-- $width = 40px -->
Then, at any point afterwards 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 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 $ or @ to denote 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 strings. This means you can NOT do things like add variables together, etc. (If you need that capability, it's time to step up to PHP, Jade, Haml or Slim.) Also, everything after the variable name is considered part of the variable value. If you wrap your string in quotation marks, the quotation marks will appear when you use the variable. 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 can be used at any later point. This extends into imported files. If you declare a variable in "master.kit", then import "beta.kit", the variable from "master" will be available in "beta". By contrast, any variables declared in "beta" will NOT be available in "master".
To use Kit, simply take any regular HTML file and rename it from *.html to *.kit. You can use Kit for more than just HTML. If you have a PHP file, 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 rather than *.html. Now, when you save the Kit file, CodeKit will create a PHP file.
Note: to change the extension of an HTML file in the Finder, you need to right-click the file, choose "Get Info" and then change the extension in the window that pops up. If you try to do so in the Finder window itself, Finder will actually rename the file to "*.kit.html" instead of changing the HTML extension.
Lots of people asked me to add "imports for HTML files". They don't want to use PHP just to do simple things like including a navigation bar on every page. That's the very specific problem Kit is designed to solve.
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 compiler 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.