# How do I do theme development with an example site in the repo?

**URL:** <https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136>\
**Category:** support\
**Created:** [November 23, 2015, 10:17pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136 "2015-11-23T22:17:16Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![AldenJole](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/aldenjole/32/907_2.png) [@AldenJole](https://discourse.gohugo.io/u/AldenJole)\
**Post date:** [November 23, 2015, 10:17pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/1 "2015-11-23T22:17:17Z")

</div>

It looks like all the themes include an exampleSite at the root of the project. It’s not clear to me if people are using the exampleSite for development or only a demo. I tried using it for development by symlinking the project root in the themes folder of the exampleSite but hugo didn’t like my use of symlinks. I don’t remember what errors I got but it wasn’t working. How are other people going about theme development using an exampleSite?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 23, 2015, 11:01pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/2 "2015-11-23T23:01:30Z")

</div>

> [@AldenJole](#):
>
> How are other people going about theme development using an exampleSite?

Create a copy and modify.

---

<div class="post-metadata">

**Author:** ![AldenJole](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/aldenjole/32/907_2.png) [@AldenJole](https://discourse.gohugo.io/u/AldenJole)\
**Post date:** [November 23, 2015, 11:37pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/3 "2015-11-23T23:37:44Z")

</div>

Create a copy of what? Create a copy of a theme or an example site? I understand how to have an example site but right now I have the example site in a different repo and then check the theme out in the the exampleSite/themes/ directory. I’d like to have a clean way for the example site to live in the same project as the theme without having to checkout the project twice for development: once for the example project and another time in the themes directory of the example site for the theme. To illustrate what I’m imagining, one solution would be being able to give hugo a path instead of a name for the theme, i.e., `hugo server -t ../`.

My directory structure looks like this.

```auto
    /
        exampleSite/
            themes/
            ...
        images/
            ...
        layouts/
            ...
        static/
            ...
        theme.toml

```

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 24, 2015, 11:01am UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/4 "2015-11-24T11:01:21Z")

</div>

> [@AldenJole](#):
>
> Create a copy of what? Create a copy of a theme or an example site?

The example site. The exampleSite’s main purpose is the demo site. A site should live outside of the theme, so create a copy and put it somewhere else. Then modify that.

---

<div class="post-metadata">

**Author:** ![digitalcraftsman](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/digitalcraftsman/32/4142_2.png) [@digitalcraftsman](https://discourse.gohugo.io/u/digitalcraftsman)\
**Post date:** [November 24, 2015, 7:14pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/5 "2015-11-24T19:14:53Z")

</div>

TLDR: If your setup isn’t very complicated you can mostly stay with the classic folder structure without using exampleSite. If your site/theme grows in complexity feel free to read on.

As @bep already mentioned: the exampleSite folder is mostly used to the demos at our [theme site](https://themes.gohugo.io) if you have a added some advanced logic. A lot of my themes required a custom setup that goes beyond a standard config file. For example, I added custom content to show certain features in blog posts or I’ve made use of the [data folder](https://gohugo.io/extras/datafiles/). These files are usually not part of a theme since this file reside in the root directory of a Hugo site.

Maybe it helps if you take a look at the setup of [one of my themes](https://github.com/digitalcraftsman/hugo-agency-theme/tree/master/exampleSite) to get a practical example. Another great side-effect is that I can directly ship my theme with all files that are required for the custom structure that I mentioned above.

Within the [README](https://github.com/digitalcraftsman/hugo-agency-theme) I provide some instructions for the users of how to copy the right files from the exampleSite folder to the right destination, e.g. that all files under exampleSite/data/ remain to the data/ folder in the root directory.

I hope I could clarify some things.

---

<div class="post-metadata">

**Author:** ![AldenJole](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/aldenjole/32/907_2.png) [@AldenJole](https://discourse.gohugo.io/u/AldenJole)\
**Post date:** [November 25, 2015, 2:28am UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/6 "2015-11-25T02:28:34Z")

</div>

@digitalcraftsman, thanks for creating the agency theme. It’s probably what I would use as a starting part for any single page site I want. Apparently I’m failing to communicate my problem. Your readme has a description of how to use the theme. What I need is a description of how to do theme development. For instance, I would like to have the `exampleSite` in the theme project. I would like to do `hugo server -w` from the root of the `exampleSite` directory and have it use the theme I’m building at the root of my project. Maybe this is impossible but I’m just wondering how people go about developing themes. Right now I just have my example site as a separate project and checkout the theme project in the themes directory but this seems less than ideal. Do you use the example site for theme development or do you just throw that in there when you’re done?

---

<div class="post-metadata">

**Author:** ![digitalcraftsman](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/digitalcraftsman/32/4142_2.png) [@digitalcraftsman](https://discourse.gohugo.io/u/digitalcraftsman)\
**Post date:** [November 25, 2015, 12:57pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/7 "2015-11-25T12:57:05Z")

</div>

@AldenJole The following wouldn’t work:

```auto
cd exampleSite
pwd
> themes/THEMENAME/exampleSite/
hugo server -w

```

This only works on the demo site because a shell script generates the site. It detects standard folders like `data` and `content` and or a custom config file within `exampleSite`.

All the custom files and folders copied into a temporary folder that represents a complete Hugo site that you would generate with `hugo new site SITENAME`. Now Hugo finds everything in the root folder is now able to render the demo site without any issues.

---

<div class="post-metadata">

**Author:** ![AldenJole](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/aldenjole/32/907_2.png) [@AldenJole](https://discourse.gohugo.io/u/AldenJole)\
**Post date:** [November 29, 2015, 11:02pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/8 "2015-11-29T23:02:29Z")

</div>

But how does the exampleSite know to use the THEMENAME theme?

---

<div class="post-metadata">

**Author:** ![digitalcraftsman](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/digitalcraftsman/32/4142_2.png) [@digitalcraftsman](https://discourse.gohugo.io/u/digitalcraftsman)\
**Post date:** [November 30, 2015, 6:43pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/9 "2015-11-30T18:43:08Z")

</div>

The [shell script](https://github.com/spf13/hugoThemeSiteScript/blob/master/generateThemeSite.sh) that generates the demo sites knows two possible ways to create the demo pages for your theme:

- If your theme does not contain an `exampleSite` folder it generates yours like you would run the following commands in the terminal:

```bash
hugo new site .
mkdir themes
cd themes
git clone git@github.com:path/to/theme.git
cd ..
hugo server --watch --theme=THEMENAME 

```

It’s like using the default config file generated by Hugo (with `hugo new site .`) where you just specify which theme should be used.

- The second option is to provide an `exampleSite` folder. The bash scrip will detect `exampleSite` and copies everything into the root directory of the Hugo site. Now your custom config file, your own content files etc. will be used instead.

But I think @bep could clarify the details if needed since the created the bash script.

However, after taking a look at your Github profile I guess you’re currently working on the [CFA Brigade Theme](https://github.com/AldenJole/cfa-brigade-hugo-theme). No it depends on the customization of the config file if you need `exampleSite`. For example, this is the case if you added new variables under `params` in the config file.

Within the layout you’re using custom variables from `params`. Without an example config file in `exampleSite` Hugo and the bash script wouldn’t which values to insert. Hugo would treat your theme as under the first bullet point by using the default configuration.

---

<div class="post-metadata">

**Author:** ![AldenJole](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/aldenjole/32/907_2.png) [@AldenJole](https://discourse.gohugo.io/u/AldenJole)\
**Post date:** [November 30, 2015, 7:05pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/10 "2015-11-30T19:05:03Z")

</div>

My understanding is that what I want to do is not currently possible. If I could specify the theme by path, then I could do something like

```auto
git clone git@github.com:path/to/theme.git
cd theme
hugo server --watch --themePath . --source exampleSite

```

This would allow `hugo server` to `--watch` both the theme and the example site. As it is currently I do

```auto
git clone git@github.com:path/to/site.git
cd site
mkdir themes
cd themes
git clone git@github.com:path/to/theme.git
cd ..
cd ..
hugo server --watch

```

This works okay for development but it doesn’t keep the theme and the exampleSite in the same repo which is less than ideal. I think hugo is also watching the `theme/.git` which could eventually cause problems. If I ever wanted the theme to show up on the themes page, I would have to copy the example site repo into the theme repo which would cause the example sites to get out of sync.

---

<div class="post-metadata">

**Author:** ![digitalcraftsman](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/digitalcraftsman/32/4142_2.png) [@digitalcraftsman](https://discourse.gohugo.io/u/digitalcraftsman)\
**Post date:** [November 30, 2015, 7:56pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/11 "2015-11-30T19:56:36Z")

</div>

A few moments ago I discovering your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site). And with exampleSite do you mean this repo? Because this could explain some confusion.

The theme itself is in it’s own self-contained repository. This would allow you to distribute it easily. I someone wants to setup a new website with your theme, you can treat the site and the theme as two independent peaces of code.

For the setup you instruct the user to create a new Hugo site and to download the theme into the themes folder.

```auto
hugo new site .
mkdir themes
cd themes
git clone git@github.com:path/to/theme.git
cd ..
hugo server -w -t=themename

```

Since your theme depends on a customized config file you need to distribute a version with default values with the **theme**. Before running `hugo server -w -t=themename` this config file needs to be copied into the root directory.

You could apply the same steps to your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site). Just create a `themes` folder, clone the theme into this folder and your site should run as wished. Your website and theme remain independent.

* * *

Now we can demistify `exampleSite`. With `exampleSite` I don’t refer to your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site). You can name it however you want. It does not affect the use of Hugo at all.

With `exampleSite` I mean a folder, not a repository, that is placed inside a theme. Let’s take a look at the [Cactus theme](https://github.com/digitalcraftsman/hugo-cactus-theme/tree/master/exampleSite). I’ve created an `exampleSite` folder within this theme.

You could create and `exampleSite` folder in your [theme](https://github.com/AldenJole/cfa-brigade-hugo-theme) and place there the needed config file for the theme. It doesn’t need to be the config file of your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site). Just a config file with default values is required. Now you’ve a place where the users can find the config file if they want to setup their own website with your theme.

> If I ever wanted the theme to show up on the themes page, I would have to copy the example site repo into the theme repo which would cause the example sites to get out of sync.

You don’t have to put your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site) into `theme/THEMENAME/exampleSite`. They both stay independent.

Maybe you want to share the theme with others and present it under the theme site. In order to generate a demo we would need to have a config file for your theme. Like new users how setup a website with your theme, the config file needs to be copied into the root directory.

Hugo is now able to generate your a demo. `exampleSite` is just used to ship your theme will all things that are necessary to run your theme.

We don’t need your [main Hugo site](https://github.com/AldenJole/cfa-brigade-hugo-example-site) in order to create a demo. We need just the theme and all the required files (like the config file).

---

<div class="post-metadata">

**Author:** ![mattstratton](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/mattstratton/32/24584_2.png) [@mattstratton](https://discourse.gohugo.io/u/mattstratton)\
**Post date:** [November 8, 2016, 12:36pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/12 "2016-11-08T12:36:06Z")

</div>

Okay, I’m having a similar issue.

What I do, is have the theme I am working on in its own GH repo. I then use the ExampleSite directory in that repo as the site that I “build” to test my theme. If we assume I created a theme called `castanet` then inside the examplesite directory I make a `themes` directory and inside there create a symlink of `castanet -> ../../castanet`

(Oh, and inside examplesite I create a .gitignore that ignores the themes directory)

This works quite well - I can run `hugo server` inside the examplesite directory. But “watch” doesn’t work - what do the rest of you do for testing your theme while developing it?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 8, 2016, 2:09pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/13 "2016-11-08T14:09:09Z")

</div>

This works exelent with `hugo server` for me:

> <https://github.com/bep/docuapi/blob/master/exampleSite/config.toml#L2>

But only after this fix:

> <https://github.com/gohugoio/hugo/commit/f0af80753c85d7f06fdebdc451ac2b3c69cca85c>

(which isn’t in a Hugo release, must build the source, go get etc.)

---

<div class="post-metadata">

**Author:** ![digitalcraftsman](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/digitalcraftsman/32/4142_2.png) [@digitalcraftsman](https://discourse.gohugo.io/u/digitalcraftsman)\
**Post date:** [November 8, 2016, 9:29pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/14 "2016-11-08T21:29:25Z")

</div>

Defining `themesDir = "../.."` in the config file makes the exampleSite folder working out of the box as complete Hugo website. But if users wan’t to use the config file for their actual project they would have to remove the `themeDir` variable. Otherwise, Hugo would look at the wrong place for a theme.

Is this a tradeoff?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 8, 2016, 9:45pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/15 "2016-11-08T21:45:19Z")

</div>

> [@digitalcraftsman](#):
>
> Is this a tradeoff?

Let it put it this way: The theme I linked to would not have existed without that trafeoff. So def worth it. There are other current workarounds, too, like:

```auto
env HUGO_THEMESDIR="../.." hugo server 

```

Should also work.

But if I cannot clone a random theme and cd into the exampelSite and just build it … then I would look at it as a buggy theme.

That said, there are improvements to be had in the whole “theme resolving” area. Happy if someone could fix it.

---

<div class="post-metadata">

**Author:** ![mattstratton](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/mattstratton/32/24584_2.png) [@mattstratton](https://discourse.gohugo.io/u/mattstratton)\
**Post date:** [November 11, 2016, 2:52pm UTC](https://discourse.gohugo.io/t/how-do-i-do-theme-development-with-an-example-site-in-the-repo/2136/16 "2016-11-11T14:52:54Z")

</div>

This worked like a charm. Thanks!