App Basics — Getting Started
1. Drag & Drop

To get started, drag your website's project folder onto the CodeKit window. You'll see an overlay appear. Drop the folder in the top section to create a new project. (If you're wondering what that bottom section is for, read the "CodeKit Frameworks" topic.)

CodeKit is now watching for changes to all files in that folder. Whenever you save one, the app will process it appropriately and then refresh your browser.

2. Preview

Next, click the "Preview" button in the top-right corner of the window. This opens a special address in your web browser that connects to a server inside CodeKit. This address always shows your currently selected project. CodeKit will automatically refresh every device that's viewing this address; just enter it on your iPad, iPhone, Droid, etc.

If your project uses complex things like PHP, Cookies, or POST requests, there's one switch to flip. See the "Complex Sites" section in the "Browser Refreshing" topic for details.

3. Tweak The Settings

The next thing you'll probably want to do is adjust the settings for your project. Do you want your CSS compressed? Should CodeKit minify your Javascript files when you save them? What syntax warnings do you want to be notified about? You can configure all of this and much more in the Project Settings area. To get there, click the gear icon in the command bar: the black bar across the top of the window. There are tons of settings, organized by category on the left side of the window. The ones you're most likely to adjust right off the bat are under the Languages section.


Set Defaults For New Projects

When you add a new project to CodeKit for the first time, the app sets default options for that project. You can customize these defaults. To do so, choose File > Edit Defaults For New Projects from the menubar. This will open the same Project Settings drawer you're used to, but you'll see a striped bar across the top of CodeKit's window. Adjust the settings as you'd like, then click Save. Those settings will now be used anytime you add a folder to CodeKit that's never been in the app before.


Config.CodeKit Files

CodeKit stores all your project's settings in a file named config.codekit. Anytime you change a setting in the app, that file gets updated immediately. If you remove the project from CodeKit and then add it back to the app later or add it to CodeKit on a different Mac, the app reads that configuration file and recreates your project exactly as it was. I recommend you keep only a handful of projects in CodeKit at once. Remove ones you're not working on and add them back when you are; that keeps resource-use low.

App Basics — Browser Refreshing
How It Works

CodeKit has a built-in web server that hosts your currently-selected project. CodeKit automatically refreshes every browser that is connected to this server. Click the Preview button in the top right corner of the window to open the server's address in your browser. Then, enter the same address on your iPad, iPhone or other device. (Be sure each device is connected to the same WiFi network as your Mac!) As you save files, CodeKit will reload everything.


Important: Complex Sites

If your site requires server-side processing (PHP, POST requests, cookies, etc), there's one switch to flip. Follow these steps:

  1. Configure an external server (like MAMP) to host your project, just as if you were not using CodeKit.
  2. Open the Project Settings in CodeKit and select the Browser Refreshing category.
  3. Flip the External Server Required switch ON.
  4. Fill in the External Server Address field. (The address you would enter in your browser to access the server you set up in step 1.)

IMPORTANT: you still go to the address for CodeKit's internal server (the one that opens when you click the "Preview" button). That's the only address that CodeKit will reload. If you open the External Server address directly, that page will not auto-refresh.


The Server Popover

Click the Server button in CodeKit's toolbar. The popover that appears shows the two addresses for CodeKit's internal server. The top one is simply a "pretty" version that uses Bonjour Networking. It will always have this form: http://[your computer name]:5757 If your computer name is long, you can shorten it by opening the Sharing section of OS X's system preferences.

The second address is for devices that do not support Bonjour Networking. It will always be: http://[your Mac's local IP address]:5757 Android devices and older versions of Windows do not support Bonjour, so you'll need to use this address to see your project on those devices.

Changing Networks

If you switch networks or your IP address changes, CodeKit will attempt to keep up by restarting its server automatically. If needed, you can do this manually by clicking the Restart Servers button in the Server Popover.

Working Without a Network

If your Mac is not connected to a network, CodeKit will still reload browsers running on your Mac. Just click the Preview button as normal. However, the app cannot reload any other devices until both your Mac and the device are connected to the same local area network.


It's Not Working!

First, are you viewing the right address in your browser? CodeKit will reload only the two addresses shown in the Server Popover.

Next, is your markup is valid? If there are any errors on the page, reloads may fail. Are all your tags closed properly, etc? Make sure your stylesheets are added with a <link> element in the <head> section. If you add stylesheets to the page like this: <style> @import 'someFile.css'; <style> CodeKit will not see them. (That's also really bad practice; it makes pages take longer to load.)

Next, are you running any browser plugins? Some may interfere with CodeKit's reloading process. Disable your plugins or open the preview address in a different browser that does not have plugins installed. (Adobe Edge Inspect is a known incompatibility.)

Slow Performance?

If reloads are very slow or pages do not completely load, verify that you have Internet Sharing turned OFF in OS X's system preferences. Turning that on negatively affects CodeKit's server; I'm investigating why.

Using Android?

Versions of Android before 4.4 don't have a browser that will support automatic reloads. Make sure your device is on Android 4.4+

Conflicting Javascript

You might be using a javascript library that interferes with CodeKit's reloads. Any javascript that listens for changes to the DOM and attempts to respond to those changes is likely going to be a problem. The most common library that does this is 'prefixfree.js'. Try removing javascript from the page and see if reloads start to work.


Really Technical Stuff

CodeKit's server adds a short piece of javascript to the <head> element of each page. This script establishes a link between the page and CodeKit to enable live reloads. For complex sites that use an External Server, CodeKit becomes a "reverse proxy server". It simply forwards each HTTP request it receives to the External Server you specified, then listens for a response and sends it back to the browser. If your project uses an External Server, here's a few really technical things to be aware of:

Set-Cookie Headers

CodeKit strips all domain= values from each Set-cookie: header returned by your External Server. This causes the browser to store the cookie for the current document's domain, which is exactly what we want. The domain returned by your External Server will not match the domain of CodeKit's built-in server, so the browser would normally not store the cookie as instructed. Simply removing the domain value is more reliable than trying to modify it.

Gzip & Deflate

If your external server returns gzipped or deflate-ed content, CodeKit's internal server will uncompress that data before sending it to the browser. This allows the app to inspect the page content and make required changes.

SSL & HTTPS

CodeKit cannot support SSL or HTTPS connections. CodeKit intercepts messages between the browser and your External Server so that it can modify pages by adding the necessary javascript to <head> elements. This is exactly what SSL was designed to prevent!

File Uploads

If your site accepts large uploads by users (such as videos, photos, etc submitted through a form), you should not test those features while previewing the site through CodeKit's server. The upload will likely time out.


Take It Global

Enable "Port Forwarding" on your router and forward port 5757 to your Mac. Get your LAN's external IP address from Whatismyip.com. Then, have someone 3,000 miles away visit this URL: http://[external ip address]:5757/. CodeKit will serve your active project to any computer worldwide that's viewing this address. Great for showing work to clients!

It's technically possible to have CodeKit live-reload these remote computers. However, I've disabled it by default because long-distance connections involve a lot of latency, which makes the live-reloads slow and unreliable.


Why Did You Change This In 2.0?

CodeKit 1.0 could refresh any address, but only in Chrome and Safari. Now, CodeKit can refresh any desktop browser as well as devices like iPhones, iPads, Androids, PCs and more. It was not possible to do that using the refresh method from CodeKit 1.0. So, I changed it.

App Basics — Critical Things To Know
Using CodeKit With Git or Subversion

Before you perform any action that will change large numbers of files (switching branches, rebasing, pull requests, etc.) you MUST tell CodeKit to ignore file changes in the project folder. To do that, bring up the Projects Popover and uncheck the box next to the project's name. (If you have the Projects Sidebar open, you can also uncheck the project there.) When you're finished with source-control actions, simply recheck the project to tell CodeKit to watch for changes again.

Why is this necessary?

Because there's no way for CodeKit to tell what changed a file. The filesystem events look the same whether Git changes a file or you save it in your editor. When Git changes tons of files at once, CodeKit attempts to process them, but finds that the filesystem is mutating underneath it — files the app expected to find are suddenly missing, or change right in the middle of compiling. This can, in the worst cases, cause a crash. So pause your project before using source-control!


Safe Start

If you have trouble with CodeKit, you can reset the app by quitting it and then relaunching it while holding down the shift key. This will clear out all existing data and give you a fresh start but will keep your preferences intact.


Dropbox Compatibility

If you add a project to CodeKit that resides in your Dropbox folder, it will work until it doesn't. For some reason, the Dropbox app interferes with the filesystem events that CodeKit reads to detect changes. The problem is intermittent. If CodeKit stops responding to file changes, take your project folder out of Dropbox.


Projects On Remote Disks

If you add a project to CodeKit that is on a remote disk (like an Apple Time Capsule or an office server), your network connection MUST be fast and reliable. If there is high latency between your Mac and the remote disk, the app will function very poorly and may even become unstable. You should be on a solid Wireless-N connection and your network traffic needs to remain low. (If your coworker is streaming Netflix and transferring files, you will suffer!) Depending on the speed of your network, working on a remote disk can be very, very painful.


UTF-8 Text Encoding Required

CodeKit requires files to be encoded in UTF-8 format. Most of the languages in CodeKit will fail (as will the app itself) if you attempt to compile a file that is not UTF-8. This also extends to CodeKit's internal server: it expects all text files to be UTF-8 and will always send content with UTF-8 encoding.


Vim Compatibility

If you use MacVim, you might find that CodeKit fails to compile files as you save them. To solve this, you must disable swap and backup files in .vimrc. Use set nobackup, set nowritebackup and set noswapfile.

App Basics — CodeKit Frameworks
What Are CodeKit Frameworks?

CodeKit Frameworks are collections of files that are shared across all your projects. Here's the problem: you've likely got some custom boilerplate code that you use in every project — a starter Sass stylesheet or a Javascript file with a bunch of custom functions. Normally, you'd copy these files into each new project and then use them. But when you change one of these files, you've got to remember to copy those changes to all the other projects that use them. Which project has the latest copy of your starter files? Ugh.

With CodeKit, you simply stick those custom files in a folder and then add that folder to the app as a CodeKit Framework. Let's say you have a file called "starter.sass" in your CodeKit Framework. Now, in every project you can simply write @import "starter.sass"; in that project's stylesheet and CodeKit will magically make it work. Meanwhile, there's only one copy of "starter.sass" on your disk and anytime you change it, CodeKit will automatically recompile every file that imports it!


Structuring Frameworks

Ideally, you should keep your CodeKit Framework folders FLAT. That is, don't use subfolders within them. This lets you write simple import statements that use just a filename.

If your Framework folders have subfolders, you need to include the relative path from the Framework folder to the file you're trying to import. Example: @import "subfolderName/file.sass";. Note that you do NOT include the name of the Framework folder in the path.


Using Multiple Frameworks

If you add multiple CodeKit Frameworks to the app, you can select which ones are "active" for each project. To do so, select a project, open the Project Settings area and then select the CodeKit Frameworks category. Simply uncheck the Frameworks that should NOT be used for this project.

It is not possible to define the order in which Framework folders are searched for an imported file. If two CodeKit Frameworks both contain a file named "standard.scss" and you write @import 'standard'; in a *.scss file, either Framework file may be used in that spot and the one used may change each time you compile the file because Framework folders are searched in random order to match import paths. Be careful about name collisions like this.

App Basics — Bower
How It Works

Bower lets you download and install over 6,000+ components. To use it, just click the Assets button in CodeKit's toolbar.

A new area will open and CodeKit will automatically fetch the latest list of available components from the Internet. When the list is downloaded, click the cloud button in each row to install that component and any dependencies into the current project. To install multiple components at once, select multiple rows and click the cloud.


The "Bower_Components" Folder

Installed components are placed in a special folder named "bower_components". Do not move items out of that folder; use them from the location where they're installed. This way, you can re-open the Assets area in CodeKit and update installed components to the latest versions with a single click. If you move the components, you lose the ability to easily update them.

By default, the bower_components folder is placed at the root of your project. You can change this in the Project Settings area, but do so before installing any components. If you change it after installing components, you'll need to delete the old bower_components folder and then re-install any components that were in that folder (CodeKit won't automatically move your old bower_components folder to the new path).


Updating Installed Components

Simply open the Assets area, select the Installed tab and then click the checkmark icon next to the component you want to update. You can also update all installed components at once. To do this, click the menu icon to the right of the tabs and choose Update All Installed Components. Bower will automatically update dependencies as needed.


The 'All Components' Tab

There are over 6,000 components registered with Bower. To see all of them, select the All Components tab. Be careful: many of the entries are junk or outdated. You can add a component to the Favorites tab by clicking the star icon on the left side of each row.

There are frequently multiple entries for the most popular components, such as jQuery. One entry will be the repository where jQuery itself is developed — a collection of source files that get built into jQuery. This is likely not the entry you want. What you want is the entry where the actual compiled, production release of jQuery is located. (These are often called "shim" repositories.) It can be confusing, so I've pre-populated the Favorites tab with the correct entries for the most popular components.


Power User Features

Right now, CodeKit does not support .bowerrc files. It won't automatically update them for you, nor will it read them to determine which components you want to install. Bower, as implemented in CodeKit, is designed for folks that don't want the hassle of command lines and configuration files. I plan to gradually add support for advanced Bower features in future releases.

App Basics — FAQ
Do I have to install anything else to make CodeKit work?

Negative, Ghostrider. Everything you need comes with the app and just works. Whatever language you pick, it's ready to go. And CodeKit only activates the parts that you need, as you need them, so it doesn't waste system resources.


How can I see which version of each language is in CodeKit?

Open the About window.


Does CodeKit use custom versions of Less, Sass, etc?

No. There is no difference between using these tools inside CodeKit and using them on the command line.


How many files can CodeKit watch at once?

There is no limit. However, you should pause projects you're not working on by un-checking them in the Projects Popover or the Projects Sidebar. That will keep the app responsive and reduce system resource use.


Why isn't CodeKit available in the Mac App Store?

For several reasons. First, I update the app frequently and don't want to wait on Apple to approve my changes. Secondly, I can't sandbox CodeKit without causing you a lot of hassle (constant "permission" alerts, etc) and I don't want to ruin the "it just works" experience with that crap. Thirdly, I think Apple has enough money and pillaging indie developers for 30% of their revenue is grossly unwarranted. Apple has so much cash, all they can think to do with it is return it to shareholders. I believe indie developers can put that money to better use, so I don't support Apple's 30% tax. It's far too high.


Why isn't CodeKit free and open source?

It's my full-time job. I do this for a living; not a hobby. While I certainly love and appreciate all the free software in the world, I have to eat and pay rent. Selling CodeKit rather than giving it away allows me to work on the app full-time, which means you get updates sooner and support when you email me.


Okay, then why is CodeKit $29 when similar apps are $9.99?

For the same reason a Macbook Pro does not cost the same amount as an Asus netbook.


What Happened to CodeKit 1.x?

See here for details.


I'm on Windows. What do you recommend I use to work with Less, Sass, etc?

A Mac.


Is there a version of CodeKit for Snow Leopard or Lion?

CodeKit 1.x will run on OS X Lion (10.7). CodeKit 2 requires OS X Mountain Lion (10.8) or newer. There is no version of CodeKit that will run on Snow Leopard (10.6) or older operating systems.


What Apps do you use?

Tower for version control. Transmit 4 for FTP. Safari as my primary browser with no flash installed and Chrome as a fallback for flash sites. The Ghostery Plugin for to keep some semblance of online privacy. Adobe CC for designing stuff. Querious for SQL work. MAMP to run websites locally. I love iWork (the old versions; the new ones are currently terrible) and don't even have MS Office installed. I have copies of Coda, Espresso, Sublime Text 3 and Textmate 2; none of which I'm entirely happy with. I also use 1Password 2, which is a lot better than the previous version. And finally, I use Apple Mail and iCal. Both of which routinely tick me off.


What's your hardware setup?

I use a first-generation Retina Macbook Pro 15" with a 512GB SSD and 16GB of RAM. I connect it to two Apple Cinema Displays at my desk so I have a total of 3 screens available. This is my sole Mac. I back it up to redundant USB3 external drives — one with Time Machine and one with Carbon Copy Cloner (so I have an immediately bootable backup disk). CCC has saved my bacon several times. I also have an iPad Air and an iPhone 5.


What is the Kit language?

A really great way to do imports and variables in HTML. See here for details.

Languages — Sass
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Less
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Stylus
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Javascript (Minifier)
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — CoffeeScript
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — TypeScript
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Haml
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Slim
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Languages — Kit
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 HTML, so the Kit language is great for building static sites.


Imports

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.

Multiple Imports

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 -->
The "Partial" Convention

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:

  1. Look for "someFile.kit" in the same folder as "master.kit"
  2. If that fails, look for "_someFile.kit" in the same folder
  3. If that fails, look for "someFile.kit" in all CodeKit Framework folders
  4. 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.


Variables

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.

Really Flexible Syntax

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 Variables Are Strings

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.

ONE Variable Per Comment

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 my tear the space-time continuum.

Variable Scope

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".


Getting Started

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.


Why Does Kit Exist?

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.

Why Didn't You Just Use HTML?

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.

You're Locking Us Into CodeKit!

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.

Languages — Markdown
What Is Markdown?

Markdown is a text-to-HTML language for web writers. It lets you write and structure text without putting in HTML tags. A compiler then processes your *.md file and turns it into a *.html file by adding all the necessary tags. Read the official specification on Daring Fireball.


Compiling Options

CodeKit compiles Markdown files using the Discount Compiler. Discount is blazing fast and offers several additions to standard Markdown syntax. When you select a Markdown file in CodeKit, you'll see these options in the Inspector pane:

Enable SmartyPants Substitutions

When this option is checked, the compiler will perform certain text replacements. Straight-quotes are replaced by curly quotes. (tm) becomes ™, (r) becomes ®, (c) becomes ©, 1/4 becomes ¼, --- becomes — and more. For a full list, read the Discount compiler page.

Allow PHP-Markdown Footnotes

This option lets you incorporate footnotes that work like reference-style links. You add a marker in the text and write your footnote below it, like this:

Here's some text with a footnote.[^1]

[^1]: And here is the footnote

When your Markdown file is compiled, the marker will become a superscript number and the footnote itself will be placed in a list of footnotes at the end of the document. You can write the footnote anywhere in your Markdown file. Note that you cannot make two links to the same footnote. If you try, the second link will be left as plaintext. For more, see this page.

Replace Tabs With 4 Spaces

This one's pretty self-explanatory.


Markdown Project Settings

To change the compiling options for every Markdown file at once, you can use Project Settings. Click the gear icon in CodeKit's toolbar, then select Languages > Markdown from the left-hand list. You'll see the same options described above. Changing them here will automatically affect every Markdown file in the project.


Changing The Output Path
Pro-tip:

If you rename or move an output file in the Finder, CodeKit automatically sets the associated Markdown file to compile to the new location. (Unless you move the output file out of the project.)

Markdown files compile into HTML files. You can control where that HTML file goes in two ways:

First, you can alter the default output path rules for Markdown files. Do this in the Project Settings area, just below the Markdown compiling options. Note: new Markdown files added to the project will adopt the new rules, but the output paths of existing Markdown files will not automatically change because that's potentially destructive. To apply the new rules to existing Markdown files, click the apply button.

Second, you can change the output path for individual Markdown files. To do this, select the file in CodeKit, then click the Target button in the Output File section of the right-hand Inspector. A sheet pops up letting you relocate and rename the output file. The output path of the file, relative to the project folder, appears next to the Target button.

Prevent Output Files

If you do not want CodeKit to compile a Markdown file when it changes, simply un-check the Output File checkbox in the right-hand Inspector. CodeKit will still refresh your browsers when the file changes.

Tools & Frameworks — Compass
What is Compass?

Compass is a CSS-Authoring framework for Sass. It provides pre-baked Sass mixins and other functionality that lets you kickstart a website quickly. For full details, see the official documentation.


Creating a Compass Project

Choose File > New Compass Project from CodeKit's menubar. Or, open the Projects Popover, click the plus button and choose the same option.

A dialog window will open asking you to pick a folder for the new project. For safety, choose an empty one!

Next, CodeKit will automatically open the Project Settings area with the Compass category selected. There's a short form that lets you customize Compass's options. (See the official docs for details on those.) When you're ready, click the Install Compass button.

Adding Compass to an Existing Project

You can add Compass to an existing project at any time. Open the Project Settings area, choose the Compass category and click Install Compass. Warning: Compass's files will overwrite existing ones with the same name.


Important: Compass Options

Compass projects are controlled by the "config.rb" file that Compass creates. To change options such as the output style for Sass files, you must edit this config.rb file. Changing the output style option in CodeKit will NOT affect Sass files in a Compass project. (The settings in "config.rb" override those in CodeKit.)

This also applies to output paths. You must edit the "config.rb" file to specify where your compiled CSS files should be placed; changing the output path for Sass files in CodeKit will have no effect on a Compass project.


Limitations

Due to some technical issues, it is not currently possible to use Autoprefixer, Bless or Libsass with a Compass project. These limitations will be removed in the near future.


Compass Plugins

If your project uses third-party Compass plugins, you'll need to switch CodeKit to use an external Compass compiler instead of the one bundled into the app. (See the "Using External Compilers" help section.) This is necessary because Compass plugins expect Compass to be running from the standard system location, not from within CodeKit's application bundle.

Alternately, you can sometimes provide a full, root-relative include path to the plugin in your config.rb file. The path will usually look something like /Library/Ruby/Gems/2.0/[plugin name]. This may not work for all Compass plugins.


Other Compass Commands

To see other Compass commands, select a Compass project and then right-click on the project name or icon in the top-left corner of CodeKit's window. Choose the Compass submenu. Here's a brief summary of what each command does:

Configure Compass

Lets you fill out a form with new Compass options and then generate a new config.rb file using those options.

Compile project

Compiles all stylesheets in your project at once and regenerates any associated assets, such as sprites.

Generate grid image

Generates a background image that you can apply to any element in the DOM (using background-image: in CSS) to see a visual representation of a grid during development. It lets you specify the dimensions of your grid to customize the image.

Show project statistics

Calculates statistics about your project such as the number of CSS rules and displays this information in a table.

Clean project

Deletes all compiled output files from the project (CSS, sprites and so forth).

View Compass documentation

Opens the Compass documentation in your default web browser.

Tools & Frameworks — Zurb Foundation
What Is Foundation?

Zurb Foundation is the mother of all responsive website frameworks. It's written in Sass and provides an overwhelming amount of features and customizations. See the official documentation for details.


How do I use Foundation in CodeKit?

To start a new Foundation project, just choose File > New Foundation Project from CodeKit's menubar. Or, open the Projects Popover, click the plus button and choose the same option.

A dialog window will open asking you to pick a folder for the new project. Make sure you choose an empty one!

Next, CodeKit will automatically open the Project Settings area with the Foundation category selected. Choose whether you want to use Foundation with or without Compass and click the Install Foundation button.

CodeKit will clone the Zurb Foundation repository from the Internet, install it in your project and then automatically compile the "app.scss" stylesheet for you. Click the Preview button and get to work!


Updating Foundation

To update the version of Foundation that's installed in your project, click the Assets button in CodeKit's main toolbar. Then, choose the Installed tab, select the row that says "Foundation" and click the checkmark button. Both Foundation and its dependencies will automatically update to the latest versions.


Internet Connection Required

Installing Foundation requires a connection to the Internet because CodeKit downloads the very latest version of Foundation from Zurb's remote repository.

Tools & Frameworks — Bourbon, Bourbon Neat
What are Bourbon & Bourbon Neat?

Bourbon is a simple and lightweight mixin library for Sass. Bourbon Neat is a semantic grid framework built on top of Bourbon. Each provides a ton of ready-to-use Sass. See the official documentation websites for full details.


Using Bourbon & Neat in CodeKit

To use Bourbon, just add this line to the top of your main Sass stylesheet and save:

@import "bourbon";

That's it. CodeKit just magically makes it work. If you want to use Neat as well, add this line instead:

@import "bourbon", "neat";
Yea, but how does the magic work?

CodeKit has bundled copies of Bourbon and Neat. When it sees those @import statements in your stylesheet, the app tells the Sass compiler where it can find Bourbon's files, even though they aren't in your project.


Optional: Install Bourbon Files

Future CodeKit updates will include newer releases of Bourbon and Neat as they become available. To have the latest Bourbon updates applied, all you'll have to do is recompile your Sass file.

Sometimes, though, you might want to "lock" a project to the current version of Bourbon. This eliminates the chance that a future version of Bourbon will break some of the Sass in your project. Open the Project Settings area in CodeKit, then choose the Bourbon category in the Frameworks section. Click the Install Bourbon Files button and select where CodeKit should place Bourbon's files.

Finally, change the @import "bourbon"; line in your main stylesheet to point to the location where you just installed Bourbon's files. From now on, CodeKit will tell the Sass compiler to use those copies of the files instead of the ones bundled into the app. Repeat the same process for Bourbon Neat.

Tools & Frameworks — Susy
What is Susy?

Susy is a responsive grid system built on top of Compass. See the official documentation for details. Susy can only be used in Compass projects.


How do I use Susy in CodeKit?

If your project does not already use Compass, first install Compass into the project. Then, just add this line to the top of your main Sass stylesheet and save:

@import "susy";

CodeKit will notice that @import statement and automatically make Susy's files available to the Compass compiler, even though they're not in your project. Just start using Susy's classes and mixins within your Sass file.


Optional: Install Susy Files

Future CodeKit updates will include newer releases of Susy as they become available. To have the latest Susy updates applied, all you'll have to do is recompile your Sass file.

Sometimes, though, you might want to "lock" a project to the current version of Susy. This eliminates the chance that a future version will break some of the Sass in your project. Open the Project Settings area in CodeKit, then choose the Susy category in the Frameworks section. Click the Install Susy Files button and select where CodeKit should place the files.

Finally, update the @import statement in your main stylesheet to point to the location where you placed the 'susy.scss' file. CodeKit will now use those copies of Susy's files instead of the ones bundled into the app.

Tools & Frameworks — Nib
What is Nib?

Nib is a CSS3 mixin library for the Stylus language. Read the official documentation for full details.


How do I use Nib in CodeKit?

Just add this line to the top of your main Stylus file:

@import 'nib'

CodeKit will notice this import statement and automatically make Nib's files available when compiling. You do not need to install Nib or add any other files to your project.


Note: Gradient PNGs

For background gradients, Nib has the ability to create a PNG image for compatibility with older browsers that do not support CSS3 gradient syntax. This feature is not supported in CodeKit because it requires you to install specific software libraries on your Mac before it can work.

Tools & Frameworks — Autoprefixer
What is Autoprefixer?

Autoprefixer adds vendor prefixes for CSS rules according to the latest information from Can I Use. You write CSS without worrying about vendor prefixes, like this:

:fullscreen a { transition: transform 1s; }

When you save the file, Autoprefixer runs and transforms that rule into cross-browser CSS:

:-webkit-full-screen a { -webkit-transition: -webkit-transform 1s; transition: transform 1s }
:-moz-full-screen a { transition: transform 1s }
:-ms-fullscreen a { transition: transform 1s }
:fullscreen a { -webkit-transition: -webkit-transform 1s; transition: transform 1s }

How do I use Autoprefixer in CodeKit?

You can enable Autoprefixer on a file-by-file basis or for all stylesheets in your project.

To do the former, select a Less, Sass or Stylus file in CodeKit and look at the right-hand Inspector panel. In the After Compiling section, there is a checkbox to enable Autoprefixer. If that box is checked, CodeKit will run Autoprefixer on the CSS file that is created when you save your stylesheet.

To enable Autoprefixer for all stylesheets in your project at once, open the Project Settings area and choose the Special Language Tools category under the Languages section.


Customizing Autoprefixer

You can set which browsers Autoprefixer should target. Open the Project Settings area and choose the Special Language Tools category under the Languages section. Edit the Autoprefixer Browser String textfield.

Warning: Autoprefixer has a very exact syntax that you must follow when modifying this setting. If you violate that syntax, the tool will not run at all. Read the official documentation before editing this field.

The default entry tells Autoprefixer to write prefixes for the last two major versions of every browser that has greater than 1% usage share plus prefixes for Firefox 17 and Opera 12.1 because those browsers are... special.


What About Standard CSS Files?

CodeKit runs Autoprefixer only on CSS files that are the output of a Sass, Less or Stylus file. If the app allowed you to run Autoprefixer on a CSS file, it would overwrite your hand-written CSS with the output from Autoprefixer. If you want to run Autoprefixer on a CSS file, simply rename the file to *.scss or *.less and then save it. (Remember: normal CSS is 100% valid in scss and less files.) This will let you run Autoprefixer without overwriting your source file.

Compass Projects

For technical reasons, Autoprefixer currently cannot be used in Compass projects. This is a limitation I hope to remove in the future.

Tools & Frameworks — Libsass
What is Libsass?

Libsass is a cutting-edge Sass compiler written in C instead of Ruby. That makes it over 10 times faster than the official Ruby Sass compiler. Libsass is freakin' fast.

WARNING: Alpha Status

Libsass is currently in alpha testing. It's not recommended for use in production yet. That said, this entire website was compiled with it, so your milage may vary.

If your Sass stylesheets are relatively simple, Libsass will likely work fine. However, you should test your CSS extensively and be skeptical. For complex projects, compile your Sass stylesheets with Libsass during development (because it's so much faster) and then, just before launch, re-compile your stylesheets with the official Ruby Sass compiler to be safe.


How to use Libsass in CodeKit

You can enable Libsass on a file-by-file basis or for all Sass files in your project.

To do the former, select a Sass file in CodeKit and look at the right-hand Inspector panel. In the Other Options section, there is a checkbox to enable Libsass. If that box is checked, CodeKit will use Libsass to compile the selected file. If the box is unchecked, CodeKit will compile with the official Ruby Sass compiler.

To enable Libsass for all Sass files in your project at once, open the Project Settings area and choose the Sass category under the Languages section. Check the Libsass box.


Libsass Limitations

As of 1 March 2014, Libsass currently has these major issues compared to the official Ruby Sass compiler:

  • @extend is not fully functional. Libsass works correctly for basic uses of @extend, but a full implementation is 2-3 months away.
  • @media blocks follow the scoping rules of pre-3.2 Sass.
  • Limited support for the new CSS filter functions.
  • Improper handling of of namespaced selectors.
  • No support for Sass 3.3 features yet, other than source maps.

The unofficial goal of the Libsass team is to reach parity with the Ruby Sass compiler by mid-summer of 2014.

Click here for the source of this information and here to see the full list of current Libsass issues.


Compass Projects

Libsass currently cannot be used in Compass projects. This limitation will be removed in the future, once both tools have evolved to support each other.


Fun Fact

CodeKit runs Libsass faster than any other tool on the planet. That's because CodeKit is written in C, so it can use Libsass without any "wrappers". Other tools are usually written in Javascript, which is still pretty fast but nowhere near the speed of C. These other tools have to run Libsass through a Javascript runtime, which is just a hair slower.

Tools & Frameworks — Bless
What is Bless?

So Internet Explorer has a bug. (I know; I hope you were sitting down.) IE 6, 7, 8 and 9 limit the number of selectors allowed in a single CSS file. Once the limit is reached, IE ignores any additional CSS in the file.

Bless counts the number of selectors in your CSS and, if needed, splits the file into two separate files linked together by an @import statement. You don't need to alter your markup or include the new CSS files; it all just works.


How to use Bless in CodeKit

You can enable Bless on a file-by-file basis or for all stylesheet files in your project.

To do the former, select a Sass, Less or Stylus file in CodeKit and look at the right-hand Inspector panel. In the Other Options section, there is a checkbox to enable Bless. If that box is checked, CodeKit will run Bless on the CSS file that's generated when your Sass, Less or Stylus file compiles.

To enable Bless for all stylesheet files in your project at once, open the Project Settings area and choose the Special Language Tools category under the Languages section. Check the Bless box.


Compass Projects

For technical reasons, Bless currently cannot be used in Compass projects.

Source Maps

Bless does not currently support source maps. If Bless changes your CSS files, any source maps that were created will no longer be valid.

Syntax Checkers — JSHint
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Syntax Checkers — JSLint
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Syntax Checkers — CoffeeLint
[Coming Soon]

I didn't want to hold up the launch just because I haven't gotten around to writing all the help content yet. I'm working on it tonight and will have it all filled in by Thursday. In the meantime, just watch the screencasts!

Advanced Features — Hooks
What Are Hooks?

Hooks are custom scripts that you want CodeKit to run when certain files in your project change. A Hook can be either an AppleScript or a Bash script.


How To Create a Hook

To add a Hook to a project, open the Project Settings area and choose the Hooks category from the left-hand list. Click the plus button to add a new Hook. Then, use the Rule Editor to specify when this Hook should be run, choose the type of script you're entering (AppleScript or Bash Script) and paste the code into the large textbox.

Hook Order

Hooks are run in the order they appear in the table. You can drag a Hook up or down to reorder it. Each Hook will be completely executed before the next one begins to run.


Stability & Performance

Be judicious when using Hooks. If you save a file six times in two seconds, CodeKit is going to dispatch your Hooks over and over. This can lead to data corruption, crashes or other unpredictable behavior. When using Hooks, be sure the previous sequence completed before you save a file again. Additionally, keep Hooks short and simple.

CodeKit caches the compiled version of each AppleScript Hook after it runs the first time. Subsequent runs should be significantly faster than the initial one. When you change the Hook's source code, the cached copy is discarded and the next run will again take a bit more time.


Security

Imagine that you have a shared CodeKit project and an evil co-worker adds this Hook: rm ~/Documents -rf. Your co-worker commits his changes, you pull them down and CodeKit syncs the project so that the Hook is now on your Mac. Are you about to delete your Documents folder next time you save?

No. CodeKit automatically recognizes Hooks that you did not create yourself and detects when a Hook's source code has changed since you last saw it. When this happens, you'll see an alert on screen and the app will automatically disable the new/changed Hooks. Once you verify that the source code for each Hook is safe, you can manually re-enable them.

That said, there is no safety net to protect you from yourself. My assumption is that if you're using Hooks, you know what you're doing. CodeKit will run exactly what you tell it to run, every time the criteria you specify are met. So if YOU add the Hook that deletes your Documents folder... I hope you have a backup.


Errors

If your Hook does not run as intended, use Console.app to view OS X's logs. CodeKit will output any error messages there.

Limitations

Hooks cannot be interactive. That is, your script cannot have prompts that require human input. CodeKit has no way to display such prompts to the user. CodeKit is also unable to display any output from scripts such as error messages (although you can launch an alert in AppleScript and log things to the system console). Finally, your script must be able to run under the privileges of the current user — sudo is prohibited.

Threading Considerations

If your Hook is an AppleScript, it will run on CodeKit's main thread because AppleScript is not thread-safe. This means that slow AppleScripts will lock up CodeKit until they complete. If your script hangs, you will need to restart CodeKit to recover. Bash scripts are run on a background thread. CodeKit should remain responsive while the script is running.

Advanced Features — Syncing Settings Across Macs
Syncing Is Automatic

Settings sync automatically in CodeKit 2! As you work, CodeKit saves every setting into a file named "config.codekit" in your project's root folder. This file is updated in real-time and lets CodeKit exactly recreate the project across computers. Here are the two most common workflows:


Source Control Workflow

You and your team use Git. Everyone has a local copy of the repo, which is also a CodeKit project. Alice is working on the file "main.scss" and changes an option for that file in her copy of CodeKit: she sets the output style to "compressed". As soon as Alice makes those changes, the app updates the "config.codekit" file. Alice pushes her changes to the remote repository.

Bob's working on the same project on his Mac. He pauses CodeKit (because he read the Critical Things To Know page about using CodeKit with Git) and does a git pull to grab Alice's changes. When Bob un-pauses CodeKit after the pull, the app reads the "config.codekit" file and instantly applies Alice's new settings in Bob's copy of CodeKit.

The "config.codekit" file is simple JSON, so you can inspect it to see what's changed and resolve conflicts just like you would with any other file. The entries are even alphabetized in 2.0!


Shared Disk Workflow

You have a central disk in your office where your project is stored. Each developer connects to that disk over the local network and each has added the same folder to CodeKit on their Mac. Whenever one person changes a setting in their copy of CodeKit, the app will update the "config.codekit" file. The remaining copies of CodeKit on everyone else's Macs will notice that change and update to reflect the new settings.

This process works, BUT it can be fragile. First, everyone MUST have a rock-solid connection with zero latency. If the connection is poor or laggy, CodeKit can't keep up with changes as they happen and the result is unpredictable. This is NOT a workflow to be used remotely; all of your developers and your shared disk must be on the same local area network. Secondly, if multiple people change settings at the same time or in very quick succession, some people's settings may not be applied because they're trumped by others.

If you use this workflow, coordinate with your teammates before changing settings. Tell them you're about to make a change and that they shouldn't make any on their copies of CodeKit until the apps finish syncing yours.


Technical Note

When you change a setting in the app, CodeKit waits exactly 2 seconds before updating the "config.codekit" file. It pauses to see if you're going to change any other settings as well so that it can minimize the number of times the configuration file is updated.

Advanced Features — Using External Compilers
What Are External Compilers?

CodeKit ships with built-in compilers for every language the app supports. However, for certain languages you can install an external compiler (usually through Ruby or Node Package Manager at the command line) and then tell CodeKit to use that external compiler instead. To do this, open the Compilers section of the app's Preferences.

Why?

The most common reason to switch to an external compiler is to have CodeKit use a beta or pre-release version of that compiler. Beta versions bring cutting-edge features, but can be unstable. By installing the beta compiler yourself and then switching CodeKit to it, you don't have to wait until the new version is officially released and makes its way into a CodeKit update.

The other common reason to do this is to use third-party plugins (for Compass) or to use "filters" in Jade and Haml. These features require the compiler to be run from the default system location rather than from within CodeKit's application bundle because they require you to install additional tools to support the filters (e.g. Discount for Markdown in Jade). For details, consult the documentation for the language you're using.


Pitfalls

There is no guarantee that newer versions of a compiler will work correctly in CodeKit. Depending on what's changed, I may have to update the app to support the newer compiler. If you switch to an external compiler, you do so at your own risk. (If you run into problems, you can always switch back easily.)


Important: RVM is not Supported

CodeKit is not compatible with RVM. If you use RVM to manage Ruby gems, you MUST run the system command on RVM before you install a gem that you intend to use with CodeKit. This ensures that the gem is installed in the system-standard location. This applies to Compass, Sass, Haml and Slim.


Older Compilers: Not Supported

Never attempt to switch CodeKit's compilers to a version older than the one that ships with the app. Doing so is almost certain to cause massive problems, including crashes and data corruption. You can see which versions of each compiler are bundled into the app by opening the About Window.