Custom Header Plugin for Movable Type

The Custom Header Plugin for Movable Type makes it easy for users to upload and customize the header for their blog. It uses javascript and Ajax to make the customization process as seamless, intuitive and painless as possible. No knowledge of HTML or CSS is required, but the theme you are using must explicitly support this plugin. Here are a list of features the plugin has:

  • Upload and crop a photo or image to use as a header
  • Automatically restricts your cropped image to the proper aspect ratio for your header (according to your theme's design)
  • If you make a slight mistake, easily re-crop the image to fine tune your header exactly the way you want it.
  • Your cropped header and the original file you uploaded is managed for you within Movable Type's asset management framework.



This plugin is installed just like any other Movable Type Plugin.


Custom Header Screenshot

Custom Header Screenshot (cropping)



Custom Header MenuTo use the Custom Header plugin you must first apply a template set to your blog that supports the plugin. You will know if you plugin supports the Custom Header plugin because a "Custom Header" menu option will appear under your Design menu.

To customize your header, select "Custom Header" from the Design menu. Then select a photo to upload and click the "Upload" button. A dialog will automatically appear allowing you to crop the photo you upload. When the area has been selected that you want to use for your header, click the "Crop" button.

That's it. Your header is ready to be used. Republish your blog and your header will appear.

Template Sets Known to Support Custom Header

Designers and Theme Developers

To add support for this plugin to your theme or template set, you will need to edit your template set's definition within its config.yaml file. The definition is simple and defines the max width and height for the header that your users will be allowed to upload. The definition looks like this:

  max_width: 780
  max_height: 125

This definition should be placed within your template set's config.yaml like so:

    base_path: templates
    label: 'My Awesome Blog Theme'
      max_width: 780
      max_height: 125

Once this is in place and a users installs this template set, then a "Custom Header" menu option will automatically appear under the Design menu.

Template Tags


This template tag puts the current blog's header asset into context. That means that because the Custom Header plugin utilizes Movable Type's asset management framework you can utilize all of MT's asset related template tags in order to display all manner of information about your header. For example, this tag will display an HTML image tag for your header:

   <img src="<mt:AssetURL>" 
         width="<mt:AssetProperty property="image_width">"
         height="<mt:AssetProperty property="image_height">>

If there is no custom header associated with the current blog then this tag will return an empty string.


This template tag returns the maximum width allowed for the custom header defined by the current template set.


This template tag returns the maximum height allowed for the custom header defined by the current template set.


This template tag puts the parent asset, or the asset from which the current asset was derived, into context. This is useful for example if you want to display not only the header image, but the original image from which the header image was cropped. For example, the following template code will display a thumbnail of the original image for the current header image:

    <mt:AssetThumbnail width="200">

Known Issues

  • This plugin currently only works for Themes and Template Sets that explicitly support the custom_header directive in their configuration files.
  • Your blog must be republished after uploading a new header.


Hey this is even better than what I was doing. But how does one add support for a theme based on the Tristan Blue 4.2? I find no config.yaml for that. Or am I just looking in the wrong spot?

Getting this work with Tristan Blue is a non-trivial task, slightly because it is a theme for which a header is not easily abstracted. Not in the classic sense anyways. The following themes are perfect for the Custom Header plugin:

  • Classic Blog
  • Professional Website (for customizing the image on the web site homepage)

As for Tristan Blue and your question however, the config.yaml for Tristan Blue can be found within the MT_HOME/addons/Community.pack/ directory of Movable Type. Look for the following in that file:

        label: Community Blog
        base_path: templates/blog
        order: 1000

And edit it so that it looks like this:

            max_width: 1182
            max_height: 130
        label: Community Blog
        base_path: templates/blog
        order: 1000

I then recommend you edit your Stylesheet template and add the following to the end of it (below the various @include directives found there):

<mt:if tag="CustomHeaderAsset">
#header {
    background-image: url('<mt:CustomHeaderAsset><mt:AssetURL></mt:CustomHeaderAsset>');

I am doing this without testing, but it seems reasonable this will work. Let me know how it goes.


If you have a chance could you do a simple, idiot proof, howto for adding this to the standard MT 4.* templates?


Byrne. All seems to be going good until I hit a brick wall. What does this mean and how can I fix it?

Got an error: Error reading /home/bgviewsb/public_html/mt/addons/Community.pack/config.yaml: Hash line over-indented

Make sure you remove any tabs from your config.yaml file (where you edited it). YAML is a very sensitive syntax.

Wow, I think I fixed it! Now to upload an image and see if it works.

What browser are you using? It does not work for me in Mac Safari, Mac Firefox 3, Windows Firefox gives me an error when I try and upload an image (SyntaxError: missing } after property list) and IE 7 will not upload the image at all.

This is what I get in Mac Safari (Version 3.1.2 (5525.20.1)) and Mac Firefox (3.0.5)

As you can see this differs from your screen shot above. The Crop and Cancel buttons are not over a yellow background, they are over the image and I cannot click them. I have a cross hair curser and if I click Crop it just resets the cropping area so I can select a new crop.

I tried with smaller images, about 1000 px wide (my size set is 975x70) and that did not help the situation.

After a couple hours of work, I think I have everything working, everything but the crop.


Ken - I will do additional browser testing today, but I did all of my work using Mac Firefox 3.0.5.

Yea, I fixed the tabs problem. Now I have a different issue (outlined above).


I have done additional testing on Firefox and Safari (both on a Mac) and have not been able to reproduce this problem. I suspect it might have something to do with ImageMagick. Do you use ImageMagick or do you use NetPBM or GD? Custom Header only works with ImageMagick at the current time.

Additional and more thorough testing will begin this week by a third party, so hopefully they will be able to reproduce this if you are still able to as well.


I have done more testing as well.

I am right now using a different computer with FF 3.0.5 Mac and not many extensions (I don't know if the extensions are the issue or not).

I did get it to work, once.

However an unable to get it to work again. Every time I chose a new image now the Crop and Cancel buttons are over the image.

When I uploaded the image used in that URL above, the Crop and Cancel buttons were below the bottom of the image.


Additionally, the Custom Header page is not displaying the Current Header Image that I cropped. I don't know if that is a caching issue or not.

Pretty sure I figured it out. Sorry for the comment spam here Byrne.

It does not like tall images. I was trying some desktop backgrounds I had saved on my hard drive, and other shots from a digital camera. It did not like the height at all. Once I cropped the images (ha ha) in Photoshop and saved them with a height of say 500 or 600 px tall, everything worked very well.

I will have to test out some pics I take from my digicam to see how that goes.

So, lets say you delete the asset and the reference to it in Asset Manager by mistake. The next time you go to the Custom Header page you are greeted with a doozy:

Publish error in template 'custom_header.tmpl': Error in tag: Error in tag: Error in tag: You used an 'mtAssetURL' tag outside of the context of an asset; perhaps you mistakenly placed it outside of an 'MTAssets' container?

Is there any way to fail gracefully in this situation?


This should be fixed by the way. Thank you Ken!

For those subscribed to this thread - I just released Custom Header 1.0, pulling the plugin out out of beta and making it work with FastCGI.


I'm using a new install of MT 4.3 and wish to install the cutomheader plugin.

I have transferred the mtstatic/plugins/ data from the archive to my $mtstatic dir and the plugins dir to my $MTHOME dir. I've also transferred the meta.yml file over to $MTHOME. Is there something I'm missing? Nothing has changed.



hi is it used for mt 3.38 ? i want use for this site:

Hey Byrne.,

Using the CustomHeaderAsset tag in a template that is background published via PublishQueue raises this error:

"Eval failure: Can't locate object method "blog" via package "MT" at /var/www/ line 190."

Works fine if built statically.

Grrr...forgot to include some details:

Tested with MT 4.23 and MT 4.34. ]

Leave a comment

what will you say?

Monthly Archives

Recent Comments