Subtext 2.5 Skin Improvements

subtext 0 comments suggest edit

Deploying a Subtext skin used to be one of the biggest annoyances with Subtext prior to version 2.5. The main problem was that you couldn’t simply copy a skin folder into the Skins directory and just have it work because the configuration for a given skin is centrally located in the Skins.config file.

elephant-skinIn other words, a skin wasn’t self contained in a single folder. With Subtext 2.5, this has changed. Skins are fully self contained and there is no longer a need for a central configuration file for skins.

What this means for you is that it is now way easier to share skins. When you get a skin folder, you just drop it into the /skins directory and you’re done!

In most cases, there’s no need for any configuration file whatsoever. If your skin contains a CSS stylesheet named style.css, that stylesheet is automatically picked up. Also, with Subtext 2.5, you can provide a thumbnail for your skin by adding a file named SkinIcon.png into your skin folder. That’ll show up in the improved Skin picker.

When To Use A Skin.config File

Each skin can have its own manifest file named Skin.config.This file is useful when you have multiple CSS and JavaScript files you’d like to include other than style.css (though even in this case it’s not absolutely necessary as you can reference the stylesheets in PageTemplate.ascx directly).

The other benefit of using the skin.config file to reference your stylesheets and script files is you can take advantage of our ability to merge these files together at runtime using the StyleMergeMode and ScriptMergeMode attributes.

Also, in some cases, a skin can have multiple themes differentiated by stylesheet as described in this blog post. A skin.config file can be used to specify these skin themes and their associated CSS file.

Creating a Skin.config file

Creating a skin.config file shouldn’t be too difficult. If you already have a Skins.User.config file, it’s a matter of copying the section of that file that pertains to your skin into a skin.config file within your skin folder and removing some extraneous nodes.

Here’s an example of a new skin.config file for my personal skin.

<?xml version="1.0" encoding="utf-8" ?>
    <SkinTemplate Name="Haacked-3.0">
            <Script Src="~/scripts/lightbox.js" />
            <Script Src="~/scripts/XFNHighlighter.js" />
            <Style href="~/css/lightbox.css" />
            <Style href="~/skins/_System/csharp.css" />
            <Style href="~/skins/_System/commonstyle.css" />
            <Style href="~/skins/_System/commonlayout.css" />
            <Style href="~/scripts/XFNHighlighter.css" />
            <Style href="IEPatches.css" conditional="if IE" />

If you compare it to the old format, you’ll notice the <Skins> element is gone and there’s no need to specify the TemplateFolder since it’s assumed the folder containing this file is the template folder.

Hopefully soon, we’ll provide more comprehensive documentation on our wiki so you don’t have to go hunting around my blog for information on how to skin your blog. My advice is to copy an existing skin and just tweak it.

Found a typo or error? Suggest an edit! If accepted, your contribution is listed automatically here.



19 responses

  1. Avatar for Adam
    Adam June 6th, 2010

    It looks like you have a missing tag or something, because your fonts go back to courier new after the text Skins.User.config file for you home page.

  2. Avatar for Adam
    Adam June 6th, 2010

    Looks like its a rogue block looking at your source.

  3. Avatar for haacked
    haacked June 6th, 2010

    @Adam thanks. I fixed it.

  4. Avatar for Bradley Landis
    Bradley Landis June 8th, 2010

    What is the best way to work with the project while developing skins? I installed Subtext, created a blog, copied an existing skin to a new directory and updated the skin.config. Then I made a few changes to the page template and selected the new skin. Everything worked great. But now when I make more changes, no matter what I do, I can't get the changes to take effect. Does it have to do with the pre-compilation?

  5. Avatar for haacked
    haacked June 9th, 2010

    @Bradley, that probably has to do with caching. Try making a change to web.config (like adding a space somewhere) and save the file. Then refresh your website.

  6. Avatar for Bradley Landis
    Bradley Landis June 9th, 2010

    Thanks. It turned out to be something very simple. The skin that I copied had files in its Control folder called _Header.ascx and Header.ascx. I was editing the wrong the one.

  7. Avatar for raffaeu
    raffaeu June 18th, 2010

    Hi Phil, I just migrated my blog from 2.1 to 2.5.
    It's working now but there are plenty of bugs in the migration process and now the configure section raises unhandled exceptions.
    Where I can post these errors in order to help you?
    Great job, anyway, it's seems really faster than before!

  8. Avatar for haacked
    haacked June 19th, 2010

    @raffaeu Please post them to Thanks!!!

  9. Avatar for raffaeu
    raffaeu June 20th, 2010

    I will Phil. Sorry about the late for the MAC skin but as you may noticed WH4L just ruined my life in the latest 2 weeks as they wiped everything. Fortunately SubText is very easy to restore if you keep the backup of SQL.

  10. Avatar for Herts
    Herts January 17th, 2011

    We must remember that viagra take the juice before cialis under identical conditions viagra so you can keep each other

  11. Avatar for Pes Patch
    Pes Patch March 16th, 2011

    Nice article.Thank you Phil

  12. Avatar for vCloud
    vCloud April 3rd, 2011

    Really great information for the subtext user as there was a lot of problem before the release of this version. The application .config file looks useful to everyone and explanation given by you for creating config files is easily understandable. I hope we will be soon come across lot of update on this version on your wiki. I definitely follow your advice. Thanks for sharing this information with use which will be useful for us to large extent.

  13. Avatar for Pes 2012
    Pes 2012 May 7th, 2011

    Its ver useful tips for improvement

  14. Avatar for vBulletin services
    vBulletin services May 9th, 2011

    This is always a good idea to have a style sheet rather then just placing the whole source code in web page, that make Google bot very hard to even find good content on a page. Meta keywords and description is still very important. Rather then just having the js file if i use a open source js file would that even work?

  15. Avatar for ATL Escorts
    ATL Escorts October 14th, 2011

    This is strange thing.Your observation is fine from one corner if we see things.Lots of people do have this view but things are like that.

  16. Avatar for Harry
    Harry December 17th, 2011

    The application .config file looks useful to everyone and explanation given by you for creating config files is easily understandable. I hope we will be soon come across lot of update on this version on your wiki.

  17. Avatar for Wojtek
    Wojtek January 28th, 2012

    Hi Phil, thanx for your artile, very usefull :)

  18. Avatar for Imobiliarias em Sao Paulo
    Imobiliarias em Sao Paulo March 27th, 2012

    The application .config file looks useful to everyone and explanation given by you for creating config files is easily understandable. Thanks!

  19. Avatar for finewallsticker
    finewallsticker August 25th, 2012

    Good one! Where are your contact details though?