App Basics — Getting Started

1. Drag & Drop

To start, drag your website's folder onto the CodeKit window. An overlay appears. Drop the folder in the top section to create a new project. (Read the "CodeKit Frameworks" topic for info about the bottom section.)

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

2. Preview

Click the "Preview" button in the top-right corner. This opens a special address in your web browser. CodeKit will automatically refresh every device that's viewing this address; just enter it on your iPad, iPhone, Droid, etc.

If your project needs server-side processing (PHP, Cookies, etc), there's one switch to flip. See the "Complex Sites" section in the "Browser Refreshing" topic.

3. Tweak The Settings

You can configure hundreds of things in the Project Settings area. To get there, click the gear icon in the top-left corner of the window. Settings are 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.

Choose File > Edit Defaults For New Projects from the menubar. This will open the same Project Settings area you're used to, but you'll see a yellow bar across the top of CodeKit's window. Adjust settings and 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 active 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.) CodeKit will reload everything.

Basic Sites

If your project uses only static files like html, javascript, css, images and so on, there's nothing to configure. Just click the Preview button and get to work. If your site uses server-side processing (PHP, Cookies, etc.) see the next section.


Important: Complex Sites

If your site requires server-side processing, follow these steps:

  1. Configure an external server (like MAMP) to host the project.
  2. Open the Project Settings and select Browser Refreshing.
  3. Flip the External Server Required switch ON.
  4. Fill in the External Server Address field.
What Address Do I Enter In The Text Field?

The address of the server you set up in step one. Usually, it's something like http://localhost:8888 or it might be a custom virtual host you configured, like http://mysite.dev.

What Address Do I Load In My Browser?

You ALWAYS 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 auto-refresh. Behind the scenes, CodeKit talks to your External Server, but you still visit the same preview address as you would for a basic website.


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!

See the Troubleshooting section for a walkthrough of how to diagnose issues with browser-refreshing.


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 — Troubleshooting

This page explains how to fix the two most common issues people have with CodeKit:

  1. Files have stopped auto-compiling on save
  2. Browsers are not refreshing

Files Have Stopped Auto-Compiling On Save

Step 1

Click the refresh button in CodeKit to have the app re-scan your project. Try saving the file again.

Step 2

If that did not work, you're likely seeing a bug in OS X's FSEvents API, which is what CodeKit uses to watch files. This bug causes the system to stop delivering "file-changed" notifications about certain folders and files. To fix it, perform one of the following steps. (Number 4 works for virtually everyone. The others have worked for some people, but not all.)

  1. Reboot your Mac.
  2. Rename the affected folder to something else, then rename it back (do not use "undo").
  3. Create a brand new folder, then drag the contents of the affected folder into the new folder. Delete the affected folder, then move and rename the new folder into the old one's place.
  4. Add the affected folder to the Spotlight privacy list (in system preferences) and then remove it. This forces a re-index by spotlight, which clears file information that triggers the bug in FSEvents.
Details About The Bug

Andrey Tarantsov and the LiveReload team first discovered this bug. You can get detailed information here.


Browser Refreshing Is Not Working

First, make sure you've read the Browser Refreshing section or watched the screencast. If you're up to speed on all that and CodeKit's preview server is working correctly, here's how to solve the problem:

1. Turn off Internet Sharing

Go to System Preferences > Sharing and make sure Internet Sharing is disabled. This service blocks the Bonjour name resolution that makes CodeKit's server work.

2. Check your markup

Make sure your HTML file has no errors. A missing tag or other DOM error can stop auto-refreshes. Check the web console for any reported errors. Be sure your CSS files are included correctly using <link> tags, like this:

<link rel="stylesheet" href="stylesheets/app.css">

Be sure the path in the tag is correct. Do NOT use @import statements like this:

<style> @import 'stylesheets/app.css'; </style>

Drupal 7 does this by default to combat an IE bug. They Drupal docs tell you to change this before taking your site live because it's very bad practice and slows page loads. You can use this Drupal plugin to fix the issue. Drupal 8 uses <link> statements by default.

3. Verify that </head> exists

CodeKit scans your page for the closing head tag: </head>. If that tag is missing, CodeKit will not inject the special script that makes auto-refresh work.

4. Verify that the file is UTF-8 encoded.

If your page is using a different encoding and contains non-latin characters (such as those for Cyrillic languages), CodeKit will fail to parse it correctly and therefore won't see the </head> tag to inject its auto-refresh script. The file MUST be UTF-8 encoded.

5. Disable other JavaScript

If your page has other JavaScript code running, temporarily remove that code to see if it's conflicting with CodeKit's auto-refresh script. In general, any JavaScript that attempts to respond to changes in the DOM will be a potential conflict. Prefix-free is a known incompatibility. Use Autoprefixer in CodeKit instead.

6. Disable browser plugins

Some browser plugins are incompatible with CodeKit's auto-refresh script. Adobe Edge Inspect is the most commonly-used one. Disable your plugins or try a different browser without any plugins to verify that they are not causing the problem.

7. Make sure your OS is supported

On Apple devices, you must be running iOS 6+. On Android, you must be using 4.3+. On Windows, you must be using IE10+. Older operating systems and browsers do not have support for HTML5 websockets, which is how CodeKit communicates to the browser to reload pages.


I Still Have A Problem

Send me an email with details and I'll get back to you as quickly as I can. It helps a great deal if you include a download link to the project/code that's not working so I can take a look at it on my end.

My address is: bryan at [this website's domain name] dot com


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

Sass is what CSS should be. It adds variables, nesting, mixins and more to regular CSS. CodeKit compiles Sass files into CSS files. For details about Sass, click here.


Set Compiling Options

For One Sass File

Select a file in the list and look at the right-hand inspector. Here, you can control how CodeKit compiles this file into CSS. For full details about every option, see the official Sass documentation. A brief summary for some options is below.

For All Sass Files

Open the Project Settings area and select Languages > Sass. The same options from the inspector panel (and more) are available here. Any changes you make are immediately applied to all Sass files in your project and will be used for new Sass files from then on.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Option Explanations
Output Style and Debug Info

These options control the style of CSS that the Sass compiler writes. In general, you should choose "compressed" and "none", as this will produce smaller files.

Generate a Source Map

If you enable this, CodeKit will place a *.map file next to the compiled CSS. Your browser uses this file to show you the original Sass code in the web inspector instead of the compiled CSS, which helps debugging.

Use The Libsass Compiler

Libsass is an experimental Sass compiler written in C. It's SUPER fast, but does not currently support all Sass features. For more information, click the Libsass link in the menu to the left.

After Compiling Options

For information about Bless and Autoprefixer, select each from the "Tools" category in the menu to the left.


Set The Output Path

For One Sass File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new output folder for the CSS file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated Sass file. (Unless you move the output file outside of the project folder.)

For All Sass Files

Open the Project Settings area and choose Languages > Sass. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from compiling a Sass file when it changes, un-check the Output File line in the inspector. You can also do this for all Sass files at once: open the project settings, choose Languages > Sass, uncheck the generate output files for this language box and then click the apply button.

Partials

If the name of a Sass file starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compile directly to CSS on their own.


View Linked Files

Sass files can import other Sass files. To see these relationships, open the Linked Files pane by clicking the right-most button in the toolbar at the top of the file inspector. CodeKit will show you which files import the selected one and which files the selected one imports. Note: if you see "[FW]" after a filename in this list, the imported file is part of a CodeKit Framework.

Import Globbing

As of version 2.1.1, CodeKit supports "globbing" import statements in Sass. If you write @import 'someFolder/*', all Sass files in "someFolder" will be imported in alphabetical order. When you change one of the imported files, CodeKit will recompile the base file.

Important: Variables in @import Statements

Sass allows you to use variables in @import statements. However, doing so makes it impossible for CodeKit to determine the correct links between your files. This is because the variable is not resolved until the file is actually compiled. CodeKit does not compile files as it scans for @import statements because that would be slow. Instead, it simply looks at the text following @import statements and treats that as a file path.

What Does This Break?

If you use variables in import statements, your file will still compile just fine. But "dependent" files won't. Normally, if file X imports file Y, when you save Y, CodeKit will go compile X because an imported file has changed. When you use variables in your import statements, CodeKit doesn't know about the link between X and Y, so it doesn't know that X needs to be recompiled.


Languages — Less

Less is what CSS should be. It adds variables, nesting, mixins and more to regular CSS. CodeKit compiles Less files into CSS files. For details about Less, click here.


Set Compiling Options

For One Less File

Select a file in the list and look at the right-hand inspector. Here, you can control how CodeKit compiles this file into CSS. For full details, see the official Less documentation. A brief summary of the less-obvious options is below.

For All Less Files

Open the Project Settings area and select Languages > Less. The same options from the inspector panel are available here. Any changes you make are immediately applied to all Less files in your project and will be used for new Less files from then on.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Option Explanations
Generate a Source Map

If you enable this, CodeKit will place a *.map file next to the compiled CSS. Your browser uses this file to show you the original Less code in the web inspector instead of the compiled CSS, which helps debugging.

Strict Imports

Requires all @import statements to be at the top of a file (which adheres to the W3C CSS spec). If this option is ON, you cannot use @import statements later in your files, such as inside a @media query.

Strict Math

If this option is ON, Less will only perform math operations on values immediately wrapped in parentheses. For example, if the option is ON then the 1 divided by 4 operation in this code: .class { font-size: 1/4; } would not be done unless you wrote it as: .class { font-size: (1/4); }. If the option is OFF, then the calculation would be done either way.

Strict Units

Suppose you write: .class { width: 1px * 2px; } This is technically incorrect because a length multiplied by a length yields an area, but CSS does not support specifying areas. If this option is OFF, Less assumes that you meant for one of the values to be a plain number, not a unit of length, and outputs 2px. If the option is ON, Less returns an error.

Generate Relative URLs

By default URLs are kept as-is, so if you import a file in a sub-directory that references an image, exactly the same URL will be output in the css. Enabling this option will rewrite URLs so they are always relative to the base file.

Enable IE Compatibility Checks

Ensures that images created with the data-uri function are not too large for the browser to handle.

After Compiling Options

For information about Bless and Autoprefixer, select each from the "Tools" category in the menu to the left.


Set The Output Path

For One Less File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new output folder for the CSS file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated Less file. (Unless you move the output file outside of the project folder.)

For All Less Files

Open the Project Settings area and choose Languages > Less. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from compiling a Less file when it changes, un-check the Output File line in the inspector. You can also do this for all Less files at once: open the project settings, choose Languages > Less, uncheck the generate output files for this language box and then click the apply button.

Partials

If a filename starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compiled on their own.


View Linked Files

Less files can import other Less files. To see these relationships, open the Linked Files pane by clicking the right-most button in the toolbar at the top of the file inspector. CodeKit will show you which files import the selected one and which files the selected one imports. Note: if you see "[FW]" after a filename in this list, the imported file is part of a CodeKit Framework.

Important: Variables in @import Statements

Less allows you to use variables in @import paths. However, doing so makes it impossible for CodeKit to determine the correct links between your files because the variable is not resolved until the file is actually compiled. CodeKit does not compile files as it scans for @import statements. That would be slow. Instead, it simply looks at the text following @import statements and treats that as a file path.

What Does This Break?

If you use variables in import statements, your file will still compile just fine. But "dependent" files won't. Normally, if file X imports file Y, when you save Y, CodeKit will go compile X because an imported file has changed. When you use variables in your import statements, CodeKit doesn't know about the link between X and Y, so it doesn't know that X needs to be recompiled.


Languages — Stylus

Stylus is CSS with more power and less cruft. It adds variables, nesting, mixins and more to regular CSS. It also makes punctuation like braces, semicolons and even colons optional.

CodeKit compiles Stylus files into CSS files. For details about Stylus, click here.


Set Compiling Options

For One Stylus File

Select a file in the list and look at the right-hand inspector. Here, you can control how CodeKit compiles this file into CSS. For full details about every option, see the official Stylus documentation. A brief summary for some options is below.

For All Stylus Files

Open the Project Settings area and select Languages > Stylus. The same options from the inspector panel are available here. Any changes you make are immediately applied to all Stylus files in your project and will be used for new Stylus files from then on.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Option Explanations
Output Style and Debug Info

These options control the style of CSS that the Stylus compiler writes. In general, you should choose "compressed" and "none", as this will produce smaller files. If you turn on Debug Info, each declaration in the CSS file will have a comment that tells you what line it came from in the original Stylus file. The Firebug browser plugin can use this information.

Inline CSS Imports

If you @import a CSS file into a Stylus file and this option is ON, the text of the CSS file will replace the @import statement in the final output. If this option is OFF, the import statement is copied, verbatim, to the output CSS file (since import statements are valid CSS).

Resolve Relative URL Import Paths

By default URLs are kept as-is, so if you import a file in a sub-directory that references an image, exactly the same URL will be output in the css. Enabling this option will rewrite URLs so they are always relative to the base file.

After Compiling Options

For information about Bless and Autoprefixer, select each from the "Tools" category in the menu to the left.


Set The Output Path

For One Stylus File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new output folder for the CSS file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated Stylus file. (Unless you move the output file outside of the project folder.)

For All Stylus Files

Open the Project Settings area and choose Languages > Stylus. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from compiling a Stylus file when it changes, un-check the Output File line in the inspector. You can also do this for all Stylus files at once: open the project settings, choose Languages > Stylus, uncheck the generate output files for this language box and then click the apply button.

Partials

If a filename starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compiled on their own.


View Linked Files

Stylus files can import other Stylus files. To see these relationships, open the Linked Files pane by clicking the right-most button in the toolbar at the top of the file inspector. CodeKit will show you which files import the selected one and which files the selected one imports. Note: if you see "[FW]" after a filename in this list, the imported file is part of a CodeKit Framework.

Import Globbing

As of version 2.1.1, CodeKit respects "globbing" import statements in Stylus: @import 'someFolder/*'. The app will correctly link the imported files so that when you save one, the base file is recompiled.


Languages — JavaScript

CodeKit lets you do three things with JavaScript files:

  1. Combine them.
  2. Check them for errors.
  3. Minify them to reduce file size.

Combining JS Files

Combining files reduces the number of round-trip requests between the browser and server. This makes pages load faster. There are two ways to combine JavaScript files in CodeKit:

1. In-File Statements

You can write special comments in your JavaScript files that tell CodeKit how to combine them. They look like this:

// @codekit-prepend "someFile.js"; 

...

// @codekit-append "someOtherFile.js";

You can also prepend or append multiple files at once with a comma-separated list.

// @codekit-prepend "someFile.js", "../someOtherFile.js", "../scripts/thirdFile.js";
What about @import?

When I first started writing CodeKit, I asked Brandon Eich (the guy who invented JavaScript) why the language did not have an @import statement. This was his explanation: it's incredibly easy to unintentionally "shadow" a function or variable by importing something into the wrong scope and it introduces many subtle bugs. For that reason, CodeKit only lets you combine scripts by putting one at the beginning or end of another.

But I want to build modularly!

Great. Each module should be its own file. Then, have one master file prepend/append the module files in the correct order. The only file that should ever be processed to final, production code is that master file. All the others are just imported into it. CodeKit will reprocess your master file whenever a linked file changes.

2. Drag And Drop

The in-file statements are the preferred way to combine JavaScript files. However, you can also do so via drag-and-drop.

Select the base JS file in CodeKit and then open the Linked Files pane of the Inspector Panel. Grab another JS file from the list and drop it on either the Prepends or Appends section.

To change the order of imported files, drag them up or down in each section. Note: You cannot drag to reorder imports that are created with in-file statements. Instead, change the order of the @codekit-prepend or @codekit-append statements.


Checking JS Files For Errors

Select a JavaScript file, then look at the Compiling Options pane of the Inspector Panel. There is a drop-down menu titled Check Syntax With. Select either JSHint or JSLint from the menu. When you save your file, the selected syntax checker will run on the base file and any files it imports.

Pro-tip: you can change the syntax checker option for all JavaScript files in your project at once. Open the Project Settings area, then choose Languages > JavaScript.

Interpreting Errors

Syntax issues are printed to CodeKit's log. The line number of the error appears on the left and the offending line of code as well as an explanation of the issue appear to the right.

For files that are linked together, errors are separated by file. However, all files are checked in the same scope. This means, for example, that if you declare a variable in a prepended file and then use it in a later file, you won't see an error about an undefined variable.

How do I change what's considered an error?

See the JSHint or JSLint section for details.

Skipping Issues in Linked Files

When you chain JavaScript files together, you can tell CodeKit to ignore issues in certain files. Select your JS file in the app, then open the Linked Files pane of the Inspector Panel. Next to each linked file is a shield-shaped checkbox. Uncheck that box to have CodeKit ignore syntax issues in that file.

Note: the skipped files are technically still checked, since they might define variables or functions used later in your chain. The issues for each skipped file are still presented in the log, but they will be automatically collapsed. Click the summary row for the file to see the issues.


Minifying JS Files

Minifying JavaScript files reduces their size and makes pages load faster. Select a JavaScript file, then look at the Compiling Options pane of the Inspector Panel. Click the drop-down menu labeled Output Style and choose either of the Minified options.

Pro-tip: you can change the output style option for all JavaScript files in your project at once. Open the Project Settings area, then choose Languages > JavaScript.

Source Maps

If you select Minified + Source Map, CodeKit will place a *.map file next to your minified JavaScript file. Your browser uses this to show you the original, un-minified JavaScript code in the web inspector. This lets you test your site using production, minified JavaScript but debug as if your files were not minified.

Important: It is possible to import a JavaScript file that's part of a CodeKit Framework by using the in-file statements. If you do this AND set your JavaScript file to produce a source map, you should read the CodeKit Frameworks section for important details.

What minifier does CodeKit use?

UglifyJS 2. It is not possible to use a different minifier and you don't want to. UglifyJS is faster, produces smaller files and is more customizable than every other alternative. For help configuring the minifier, see the UglifyJS section.


Setting The Output Path

For One JavaScript File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new location for the output file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated file. (Unless you move the output file outside of the project folder.)

For All JavaScript Files

Open the Project Settings area and choose Languages > JavaScript. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from processing a JavaScript file when it changes, un-check the Output File line in the inspector. You can also do this for all JavaScript files at once: open the project settings, choose Languages > JavaScript, uncheck the generate output files for this language box and then click the apply button.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Partials

If a filename starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compiled on their own.


Languages — CoffeeScript

CodeKit lets you do three things with CoffeeScript files:

  1. Combine them with other CoffeeScript AND JavaScript files.
  2. Check them for errors.
  3. Compile them to JavaScript (and optionally minify the result).

Combining Files

Combining files reduces the number of round-trip requests between the browser and server. This makes pages load faster. In CodeKit, you can combine CoffeeScript files with other CoffeeScript files AND with regular JavaScript files. There are two ways to do this:

1. In-File Statements

You can write special comments in your CoffeeScript files that tell CodeKit how to combine them:

# @codekit-prepend "someFile.coffee"; 

...

# @codekit-append "someOtherFile.js";

You can also prepend or append multiple files at once with a comma-separated list.

# @codekit-prepend "jQuery.js", "../someOtherFile.coffee", "../scripts/thirdFile.coffee";
What about @import?

CodeKit only lets you combine scripts by putting one at the beginning or end of another. You cannot import a script into the middle of another. Doing so makes it incredibly easy to unintentionally "shadow" a function or variable by importing something into the wrong scope and introduces many subtle bugs.

But I want to build modularly!

Great. Each module should be its own file. Then, have one master file prepend/append the module files in the correct order. The only file that should ever be processed to final, production code is that master file. All the others are just imported into it. CodeKit will reprocess your master file whenever a linked file changes.

How does CodeKit combine JavaScript and CoffeeScript files?

CodeKit wraps the entire contents of the prepended/appended JavaScript file in backticks and adds it to your CoffeeScript. All existing backticks in the JavaScript file are removed. The CoffeeScript compiler ignores all code escaped with backticks, so your JavaScript goes through to the final output file unmodified.

JavaScript file extension required

When prepending/appending a Javascript file to a CoffeeScript file, you may NOT omit the '.js' extension from the import path. If you write # @codekit-prepend 'someFolder/someFile', CodeKit will look for "someFile.coffee", not "someFile.js". The app never assumes you meant to import a JavaScript file unless you provide the '.js' extension.

2. Drag And Drop

The in-file statements are the preferred way to combine CoffeeScript files. However, you can also do so via drag-and-drop.

Select the base Coffee file in CodeKit and then open the Linked Files pane of the Inspector Panel. Grab another Coffee or JS file from the list and drop it on either the Prepends or Appends section.

To change the order of imported files, drag them up or down in each section. Note: You cannot drag to reorder imports that are created with in-file statements. Instead, change the order of the @codekit-prepend or @codekit-append statements.


Checking Files For Errors

Select a CoffeeScript file, then look at the Compiling Options pane of the Inspector Panel. There is a drop-down menu titled Check Syntax With. Select CoffeeLint. When you save your file, CoffeeLint will run on the base file and any files it imports.

Pro-tip: you can change this option for all CoffeeScript files in your project at once. Open the Project Settings area, then choose Languages > CoffeeScript.

Interpreting Errors

Syntax issues are printed to CodeKit's log. The line number of the error appears on the left. The name of the violated rule and an explanation appear to the right.

For files that are linked together, errors are separated by file. However, all files are checked in the same scope. This means, for example, that if you declare a variable in a prepended file and then use it in a later file, you won't see an error about an undefined variable.

How do I change what's considered an error?

See the CoffeeLint section for details.

IMPORTANT: Syntax-checking when combining JS+Coffee files

If you prepend or append a JavaScript file to your Coffee file, CoffeeLint may fail to run correctly. This is because the tool does not currently skip backtick-escaped code in your CoffeeScript file. Hopefully, this gets fixed in a future CoffeeLint update.

Skipping Issues in Linked Files

When you chain JavaScript and CoffeeScript files together, you can tell CodeKit to ignore issues in certain files. Select your base Coffee file in the app, then open the Linked Files pane of the Inspector Panel. Next to each linked file is a shield-shaped checkbox. Uncheck that box to have CodeKit ignore syntax issues in that file.

Note: the skipped files are technically still checked, since they might define variables or functions used later in your chain. The issues for each skipped file are still presented in the log, but they will be automatically collapsed. Click the summary row for the file to see the issues.


Set Compiling Options

For One CoffeeScript File

Select a file in the list and look at the right-hand inspector. Here, you can control how CodeKit compiles this file into JavaScript.

For All CoffeeScript Files

Open the Project Settings area and select Languages > CoffeeScript. The same options from the inspector panel are available here. Any changes you make are immediately applied to all CoffeeScript files in your project and will be used for new CoffeeScript files from then on.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Option Explanations
Output Style

"Regular" will place the compiled JavaScript inside of a function wrapper, which is appropriate if you're worried about global scope name collisions. The other option will exclude this function wrapper.

Generate a Source Map

If you enable this, CodeKit will place a *.map file next to the compiled JS file. Your browser uses this file to show you the original CoffeeScript code in the web inspector instead of the compiled JavaScript, which helps debugging.

Important: If you prepend/append CoffeeScript files, CodeKit takes the combined code and, before compiling it, writes it to a file in the hidden ".codekit-cache" directory in your project's root folder. This is what the source map will reference; the CoffeeScript code you see in your browser's inspector will be from this file. This is necessary because the CoffeeScript compiler cannot combine files on its own and, therefore, it cannot create a correct source map to the original Coffee/JS files. The CoffeeScript compiler can only work with one file at a time so that's what we provide it.

Minify Compiled JavaScript

Enabling this option will pass the compiled JavaScript through UglifyJS to minify it. Any source maps will be automatically updated to keep pointing to the original CoffeeScript code.


Setting The Output Path

For One CoffeeScript File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new location for the output file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated file. (Unless you move the output file outside of the project folder.)

For All CoffeeScript Files

Open the Project Settings area and choose Languages > CoffeeScript. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from compiling a CoffeeScript file when it changes, un-check the Output File line in the inspector. You can also do this for all CoffeeScript files at once: open the project settings, choose Languages > CoffeeScript, uncheck the generate output files for this language box and then click the apply button.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Partials

If a filename starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compiled on their own.


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

Markdown is a text-to-HTML language. It lets you write and structure text with a simple, natural syntax in place of HTML tags. A compiler processes your Markdown file into an HTML file by converting the special syntax into standard tags.

There is no "canonical" version of Markdown. There are many variations of the language, all with different additions. Read the original specification on Daring Fireball.


Set Compiling Options

For One Markdown File

Select a file in the list and look at the right-hand inspector. Here, you can control how CodeKit compiles this file into HTML.

For All Markdown Files

Open the Project Settings area and select Languages > Markdown. The same options from the inspector panel are available here. Any changes you make are immediately applied to all Markdown files in your project and will be used for new Markdown files from then on.

Pro-tip: You can make CodeKit use your custom settings for all new projects. Choose File > Edit Defaults For New Projects from the menubar.

Option Explanations

CodeKit compiles Markdown files using the Discount Compiler. Discount is blazing fast and offers several additions to standard Markdown syntax:

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

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.


Set The Output Path

For One Markdown File

Select the file in the list and look at the right-hand inspector panel. Near the bottom, click the target button. In the sheet that pops up, select a new output folder for the HTML file.

Pro-tip: If you rename or move an output file in the Finder, CodeKit automatically changes the output path for the associated Markdown file. (Unless you move the output file outside of the project folder.)

For All Markdown Files

Open the Project Settings area and choose Languages > Markdown. Adjust the Output Path options, then click the apply button at the top of that section. (Changes to output paths in the project settings are not automatically applied to existing files because that's potentially destructive.)

Disabling Output

To prevent CodeKit from compiling a Markdown file when it changes, un-check the Output File line in the inspector. You can also do this for all Markdown files at once: open the project settings, choose Languages > Markdown, uncheck the generate output files for this language box and then click the apply button.

Partials

If a filename starts with an underscore, CodeKit automatically un-checks the Output File line for that file. Files that start with an underscore are known as "partials". They are meant to be imported into other files rather than compiled on their own.


Frameworks — CodeKit Frameworks

CodeKit Frameworks are simply collections of files that are shared across all your projects.

The Problem

You have some code that you use in every project — a starter Sass stylesheet or maybe a JavaScript file with custom functions. Normally, you'd copy these files into each new project. But when you change one of the files, you've got to remember to copy those changes to all the other projects and you lose track of which project has the latest version, etc.

The Solution

Stick your custom files in a folder and then add that folder to CodeKit as a CodeKit Framework. Let's say you have a file called "starter.sass" in your Framework. Now, in every project you can simply write @import "starter.sass"; in that project's stylesheet and CodeKit will magically make it work. Now 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 have multiple Frameworks, you can select which ones are "active" for each project. Open the Project Settings area and select Frameworks > CodeKit Frameworks. 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';, either Framework file may be used in that spot and the one used may change each time you compile the file.


IMPORTANT: Source Maps + CodeKit Frameworks

When you use a file from a CodeKit Framework in a project and the resulting output file is set to create a source map, CodeKit will place a copy of your Framework file into a hidden directory in your project root folder named ".codekit-cache".

This makes the source map work correctly by giving it a copy of the original code to use in your browser's web inspector. If you see a reference to a file in the ".codekit-cache" folder while viewing the web inspector, remember to edit the original file in your CodeKit Framework, NOT the file in the .codekit-cache folder, which will be replaced the next time you save.

Frameworks — 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.

Frameworks — Zurb Foundation

Zurb Foundation is the mother of all responsive website frameworks. It's for building websites that scale across devices.

Foundation is built on Sass and provides an incredible amount of features and customizations. See the official documentation for details.


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

Frameworks — 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.

Frameworks — Susy

Susy is a responsive grid system built with Sass. There are two versions available in CodeKit: Susy 1 and Susy 2. See the official documentation for details.


Using Susy in CodeKit

To use the latest version of Susy (Susy 2) in your project, just add this line to the top of your main Sass stylesheet. Your project does NOT need Compass installed.

@import "susy";
Legacy Susy 1 Support

For older projects where you must use Susy 1 syntax, first install Compass into the project. Then, just add this line to the top of your main Sass stylesheet and save:

@import "susyone";

In either case, CodeKit will notice that import statement and automatically make the correct Susy files available. 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.

You can "lock" a project to the current version of Susy, which eliminates the chance that a future version will break some of the Sass in your project. Open the Project Settings, then choose the Frameworks > Susy. Click the Install Susy Files button and select where CodeKit should place the files.

Be sure to 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.


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.

Frameworks — Google Web Starter Kit

Google Web Starter Kit is a collection of boilerplate files that let you quickly build a multi-device, responsive website with modern best-practices.

It's also a really groundbreaking name for a web-related product that is so boldly different than anything that has ever come before ... wait.


Creating a Web Starter Kit Project

Choose File > New Google Web Starter Kit 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. Choose an empty one.

Next, CodeKit will automatically open the Project Settings area with the Web Starter Kit category selected. Select whether you want CodeKit to modify Web Starter Kit files after they're downloaded (see below) and click the Install button.

You'll need an internet connection for this to work. CodeKit clones the Web Starter Kit repository directly from GitHub so you get the latest files.


Let CodeKit Modify Files

By default, Google Web Starter Kit is designed to be "built" into a build folder using command line tools. This is slow and dumb because it involves duplicating every single file in the website. CodeKit is designed to work with files in-place. As a result, some changes need to be made to the Web Starter Kit files to update paths in src tags, etc. CodeKit makes four basic changes after downloading:

  1. Deletes some command line tool config files that aren't needed because you're using CodeKit instead.
  2. Moves the contents of the "app" subfolder to the root folder and deletes the "app" subfolder, because we won't be using a "build" folder.
  3. Changes some src paths in index.html and basic.html to point to correct locations.
  4. Changes main.css into main.scss so you have a place to start adding your own custom styles. (The actual content of main.css is not altered.)

CodeKit also sets output paths for all files in the Web Starter Kit project to their correct values, regardless of your New Project Defaults. For example, main.js is set to compile to main-min.js in the location where the HTML files expect to find it.

A detailed list of exactly what changes were made is printed to CodeKit's Log after installation completes. The app then compiles all relevant files once. All you need to do is click Preview and get to work.


Installing Without Changes

If you want CodeKit to install Google Web Starter Kit without making any changes, just uncheck the box before clicking the Install button. You'll receive a 100% unmodified copy of the latest Web Starter Kit files.

In order to work with this project in CodeKit, you'll need to modify the src paths yourself and set correct output paths for the Javascript and Stylesheet files within the app. To see what changes need to be made, first install Web Starter Kit while allowing CodeKit to make changes and look at the Log after installation completes.


Future-Proofing

As Google continues to work on their uniquely-and-totally-originally-named project, it's likely that files will require additional tweaks to work correctly in CodeKit. (For example, they might add another <script> tag that needs a path modified.) You may need to make these changes manually after installation until I get a chance to update CodeKit to make them automatically.

Tools — Bower

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.

Tools — 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 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 }

Using Autoprefixer in CodeKit

On a File-By-File Basis

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 for that file.

For All Stylesheet Files At Once

Open the Project Settings area and choose Languages > Special Language Tools. Check the Autoprefixer box.


Customizing Autoprefixer

You can set which browsers Autoprefixer targets. Open the Project Settings area and choose the Languages > Special Language Tools. 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 Extended Support Releases and Opera 12.1 because those browsers are... special.


Autoprefixer Limitations

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


Using Libsass in CodeKit

On a File-By-File Basis

Select a Sass file 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.

For All Sass Files

Open the Project Settings area and choose Languages > Sass. 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.

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


Libsass + Compass

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.

Tools — 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.


Using Bless in CodeKit

On a File-By-File Basis

Select a Sass, Less or Stylus file 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.

For All Stylesheet Files At Once

Open the Project Settings area and choose Languages > Special Language Tools. Check the Bless box. All stylesheets in the project will now run Bless after they are compiled.


Bless Limitations

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.

Tools — UglifyJS

[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 — 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

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.


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

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.


Handling 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's UI 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 3 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

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