sculpin/sculpin-blog-skeleton — pull request #16 by simensen (2014-01-14 07:44:38+00:00)
Title: Themed

Update to Bootstrap 3 and moved all of the templates (the "theme") to an external theme package (sculpin/bootstrap-3-blog-theme) to showcase the new theme functionality.

There might still be some hiccups, but I think that most of the functionality that was originally available in the blog skeleton are still intact.

---

To create a theme, create a directory named `sources/themes/{vendor-name}/{theme-name}`. This is treated as sort of a virtual root on top of `source`. So you can put things in there like `_layouts` and `_views` and they'll behave the same way as they do in `source`. If a file exists in `source` directly it will be used before those in `source/themes`.

To reference external theme resources (assets like css or js) use the `theme_path()` twig function. For example, if `theme_path("assets/css/style.css")` is called and it exists in `source/assets/css/style.css` it will be used instead of the version in the theme.

`assets/css/style.css` should probably be standardized. In this case, we can use `@import` to fix things. For example:

```css
@import url('../../themes/sculpin/bootstrap-3-blog-theme/assets/css/style.css');
```

This will ensure that your local project's css can inherit from a theme's style.css and build on it.

To change theme, `app/config/sculpin_kernel.yml` needs to be modified. Change the `sculpin_theme.theme` configuration:

```yaml
sculpin_theme:
theme: sculpin/bootstrap-3-blog-theme
```

---

To ship a Sculpin theme as a standalone package, use the `sculpin-theme` package type. It is not currently recommended to publish Sculpin themes on Packagist.

Here is the Bootstrap 3 Blog Theme: https://github.com/sculpin/bootstrap-3-blog-theme

To use it, configure `sculpin.json` to point to the repository directly.

```json
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:sculpin/bootstrap-3-blog-theme.git"
}
],
"require": {
"components/bootstrap": "3.0.3",
"components/font-awesome": "4.0.3",
"components/jquery": "1.9.1",
"components/highlightjs": "~7.3.0",

"sculpin/bootstrap-3-blog-theme": "dev-master"
}
}
```

---

It is not currently recommended for themes to require other external assets like bootstrap or jquery. This should be up to the user to install. This will allow them to install these assets however they want. It is acceptable to note in the installation/README what they can use to easily install these types of things, though.