Join GitHub today
Clone this wiki locally
Cufón has been designed with developers in mind. Therefore the API is simple and configuration is usually not needed at all, as most of the needed information is provided by CSS style sheets.
The short version
cufon-yui.jsfrom the cufón website and upload it to your own server.
- If you’re upgrading, just replace your old
cufon-yui.jsand you’re good to go. No need to convert your fonts again.
- If you’re upgrading, just replace your old
- Use the font converter (generator) on the website:
- Choose the font file you want to convert. Try not to enter the same file multiple times.
- In case of multiple font files, you may want to enter the font name to the font-family text box. This helps avoid naming troubles.
- Check the EULA checkbox right below the file upload fields (but only if you agree, of course).
- The default settings are good for most people. You don’t have to modify them.
- At the bottom, accept the generator terms. This is different from the EULA checkbox. Both must be checked.
- Submit the form and you’re done! If you get an error message, read it and act accordingly.
- Upload the generated .font.js file to your server. You may rename the file.
- Your HTML should look like this:
- And you’re set! To avoid hard-to-spot issues, here are a few things to look out for in your HTML:
- A transitional doctype will break line-height, use a strict or HTML5 doctype.
- Avoid whitespace (or anything else for that matter) before the doctype. This has been known to affect printing in IE.
- UTF-8 is the only supported character set. Use others at your own risk. Characters may go missing.
If you need support, we’ve got a Google Group for that, but please do try to solve the problem by yourself first. We’re busy too!
The longer version
Step 1 – Get cufón!
Updating to a newer version? Just replace your old cufon-yui.js with the new one and you’re good to go. Fonts need not be converted again.
Should you experience problems or if you just want to poke around a little, you may also use the uncompressed version, available from GitHub.
Step 2 – Generate a font
You may use the font generator at our website or run a copy of your own. If you plan on going for the latter option you’re probably clever enough to figure out how to get it running – the source is available from GitHub.
The name of the resulting file will include the name of the font and the weight of the font (as a number – 400 is equivalent to “normal” and 600 means “bold”). So, for example, the bold version of Bitstream Vera Sans would result in a file called Bitstream_Vera_Sans_600.font.js. The name of the file doesn’t actually matter at all, but it makes it easier for you to identify your fonts.
Using the generator should be pretty straightforward, but ideas that enhance usability are always welcome. Please use our Google Group for that.
Step 3 – Replace text
For the purposes of this example you may ignore everything that is not contained by
So what exactly happens here?
First, we include the YUI compressed version of cufón that you should always use.
Then we get to the magic part. We want to replace all
<h1> elements in the document. And that’s exactly what the tell cufón to do, with
Cufon.replace('h1'). Nothing else is needed, cufón will use the CSS rules associated with the elements and determine what to do. You should not place Cufon.replace inside $(document).ready or similar functionality because it will make Step 4 ineffective.
In order to avoid unnecessary duplication cufón does not come bundled with a selector engine, which means that by default you’ll only be able to use tag names (such as
Cufon.replace('#content > h1:first-child') and
Cufon.replace('#nav a') will work just fine.
Step 4 – Make Internet Explorer behave
Unfortunately one problem remains with Internet Explorer. In most cases, there is a short but visible delay before the text is replaced. You can avoid this issue by inserting the following snippet right before the closing
</body> tag (or before any external scripts such as Google Analytics):
And the delay is gone. For a more in-depth example, see API.
Note: This step will hopefully become obsolete in the future.
Using multiple fonts
To use multiple fonts you only need to specify which font you want to use and you’re set:
If not specified, cufón will use the font that was loaded last (in this case it would be Myriad Pro), which is why there was no need to specify the font in the first example.
All Cufón-enabled pages must be UTF-8 encoded. Compatible encodings, such as US-ASCII, are also fine.