Not a developer? Go to


Movable Type Themes

Each website and blog has its own purpose. There are personal blogs that share stories and photos, business blogs promoting products, store sites with information for potential customers, company PR blogs distributing press releases, and more.

Movable Type Themes for websites and blogs can be created for these sites can be created, reused, and shared.

Note: Themes are a new feature in Movable Type 5.

Installing Themes

Theme folders are placed into the themes directory in the root of the MT application directory. Transfer the theme files to the server via FTP or other method.


Some themes may require specific plugins. Install all necessary plugins before applying them as rebuilding may cause errors if special tags are necessary.

By viewing the Design > Themes screen you can determine if the theme was installed properly. Clicking the name of the theme will display general information about the theme as well as any errors if the theme is not properly packaged.

Once the theme is successfully uploaded to the theme folder, apply the theme…

Applying Themes

You can apply themes to individual websites and blogs in Movable Type. If you have a website that contains three blogs, for example, you can apply different themes to each of these blogs. Or you can apply different themes to each website and blog you operate, one by one.

Choose an appropriate theme each time you create a website or blog. Or, follow the steps below to choose a theme that already exists for websites or blogs:

  1. Click “Design > Theme” in the side menu of the website or blog.
  2. The themes already installed in Movable Type will be displayed in a list.
  3. Choose the theme you’d like to use and click “Apply Theme.”
  4. Settings for template, categories, custom fields and other items within a theme are automatically applied to those in your blog (or website).
  5. The message “Theme Currently Being Used” will appear next to the name of the theme that you applied.

If you apply a new theme to a blog (or website) that had previously already had a theme assigned to it, the old template will be completely backed up in the “Backed Up Template” section in the right side bar. None of the categories or custom fields you previously created will be deleted.

Elements of a Theme

A Movable Type blog or website theme is simply a folder with templates, static files, and a settings file.

The hierarchy looks like this:

my-theme/               <-- theme directory
    blog_static/        <-- directory of folders and static files
        images          <-- static files directory
        js              <-- another static files directory
    templates/          <-- directory of templates
        main_index.mtml <-- mtml template (movable type markup language)
    theme.yaml          <-- theme settings file (contains theme metadata, categories/folders, custom fields)
    thumb-medium.png    <-- 240px x 180px
    thumb-small.png     <-- 120px x 90px
    thumb.png           <-- 400px x 300px

There are two ways to create an original theme in Movable Type 5:

  1. Export a theme from an existing blog or website to a zip file or as a theme in the themes folder.
  2. Create a theme from scratch by bundling all the necessary files/folders into the theme folder and properly creating the theme settings file.

The export method is simpler, but the second offers more flexibility and efficiency for advanced users. Both options should result create in a set of files and folders in a theme folder as described above.

Once created themes can be shared and installed in separate MT installations.

More about each part of the theme:

Theme Settings File

The theme.yaml file is a text file formatted in YAML. It is the inventory of the theme and contains the configuration for every setting and references the templates and static file directories.

It contains key-value pairs defining metadata for:

  • theme: name, description, version, author, etc
  • templates: template type, label, output file, archive mappings, etc
  • static file directory location
  • custom fields
  • categories and folders
  • widgets and widget sets

Note: Comments can be added to the YAML file by prefixing the lines with hash tags “#”.

More about the theme registry keys.


A directory of templates is found within the theme folder. All of the template settings other than the template code itself are defined in the theme settings file.

When creating templates in a theme keep the following things in mind:

  • Templates should not include template modules from other blogs/websites (unless the blogs with templates to include will be installed before applying this them to other blogs/websites).
  • URLs to images and links should use the <$mt:BlogURL$> tag to form the url:


    <img src="<$mt:BlogURL$>images/header.png" />


    <a href="<$mt:BlogURL$>">Blog Main Index</a>
  • File paths should also be relative to the blog or website using <$mt:BlogSitePath$> to create file system paths.

    Include files like this:

    <$mt:BlogSitePath cat="folder/data.html" setvar="data_include"$>
    <$mt:Include file="$data_include"$>
  • If using categories, folders or custom fields in your templates, be sure to define them in the theme.

  • If any tags require plugins, be sure sure to mention this requirement in the theme’s description.

Static Files

Images, javascript, css stylesheets, flash, or other files which are part of the design can be packaged in a theme.

By default files with the following extensions are supported:

  • jpg
  • jpeg
  • gif
  • png
  • js
  • css
  • ico
  • swf
  • flv

Tip: Use the ThemeStaticFileExtensions config directive to specify a custom set of extensions.

To include static files in a theme:

  1. Create directories in the Site Root, the directory where the blog/website is published.
  2. Place the static files in these directories.

    Note: sub directories and static files (with allowed extensions) contained within these parent-directories will also be included.

    Typically you’ll want to include directories such as “css”, “js”, “images”, etc. These directories (in the Site Root) may contain files like this:

    html/               <-- web root
        css/            <-- static directory
        js/             <-- static directory
        images/         <-- static directory

Categories and Folders

Categories (only for blogs) and Folders can be included into the theme as well.

These are defined in the theme.yaml file.

Custom Fields

Custom Fields are defined in the theme.yaml file. The following system objects can have custom fields added to them.

  • Entry (blog only)
  • Page
  • Comment
  • Asset
  • Audio
  • Video
  • Image
  • Category
  • Folder
  • Template

System-level custom fields are not currently configurable in themes.

  • Blog
  • Website
  • User

The following types of custom fields are available:

  • Single-Line Text
  • Multi-Line Text
  • Checkbox
  • Date and Time
  • Drop Down Menu
  • Radio Buttons
  • Asset (non audio, image, or video)
  • Audio (audio asset)
  • Image (image asset)
  • Video (video asset)
  • URL (just a fancy “Single-Line Text” field)
  • Embed Object (just a fancy “Multi-Line Text” field)

Export a Theme from an Existing Blog or Website

  1. Go to Tools > Export Theme in the side menu of the website or blog to export a theme from.
  2. Configure the following options to customize what is exported


    Required. This is the name that will appear when selecting a theme to apply to a blog or website.


    Required. Used for the name of the theme directory which will be placed in the /themes/ directory and also the <$mt:BlogTemplateSetID$> of the theme. The basename may only contatin letters, numbers, dashes (-) and underscores (_).

    Theme Version

    Required. The version number should be updated each time the theme is changed so that users of the theme can identify one version from another. The version number will be displayed after the Theme Name on the Design > Themes page.

    Theme Description

    Description of the theme that appears in the theme summary on the admin screen.


    Required. Name of the author or group which created the theme to be displayed on the Design > Themes screen.

    URL for the author or group which created the theme… or for the theme’s homepage if one exists. Will be used as the url linking the Author on the Design > Themes screen.


    If the following items exist in the current blog/website, then they will be displayed and available for export.

    Select which items to include into the theme. For more fine-grained control, click the “Details” link and individual items can be selected or deselected.


    The theme can either be downloaded as a zip file or installed in the themes directory

    Note: Exporting to $MT_HOME/themes/ directory requires that the “themes” directory be writeable

  3. Click the “Export Theme” button.

Create a Theme for a Blog or Website from Scratch

It is a good first step to use the export method above to create a sample theme and then update the theme files to make desired customizations. The following presentation will help you to understand the theme framework in depth. It was originally written by Yujiro Araki, and translated by Nick.

Sharing Themes

Theme folders in the $MT_HOME/themes/ directory can be moved to other MT5.+ installations. (Newer versions of MT may support additional features that older versions do not.)

Theme folders can be archived in zip (or other) format, for easier delivery across the Internet.

Note: This document is available in Japanese