# Themes

{% subtitle %}

Limedocs comes with a default theme called `yuzu` but you can easily install, customize or even develop your own themes.

{% endsubtitle %}



## Installing and using a theme

Themes can be installed using [npm](https://www.npmjs.com/):

```shell title="Install a theme"
$ cd /path/to/my/docs
$ npm install some-limedocs-theme
```

Then reference the theme in your `limedocs.config.js` file:

```js title="Referencing a a theme"
module.exports = {
  // ...
  themeConfig: {
    theme: "some-limedocs-theme"
  }
  // ...
}
```

## Customize a theme

You can easily customize an existing theme by overriding `layouts`, `partials`, `tags`, `shortcodes` and static files by putting yours in `${siteDir}/theme`, like this:

```bash title="My site"
my-site
  ├── content
  │   ├── some-dir
  │   └── another-one
  └── theme # optional directory where to put overrides
      ├── layouts # your specific layouts (optional)
      ├── partials # your specific partials (optional)
      ├── shortcodes # your specific shortcodes (optional)
      └── static # your specific static files (optional)
```

{% alert type="info" %}

All files that you put in `theme/static` will be copied to your website static directory.

{% endalert %}

### Layouts

A theme consists of one or more layouts, and each page of your site is associated with a layout. For example, you may want to have a *home* layout for your homepage, an *article* layout for your articles, and a *contact* layout for your contact page. If a page is not explicitly associated with a layout, the `default` layout will be choosed to render your page.
Lastly, layouts can use and reuse `partials` (chunks of layouts). 


## Developing themes

Themes are written using [Nunjucks templating engine](https://mozilla.github.io/nunjucks/) (similar to Jinja, Handlebars / mustache). When developing themes for Limedocs, you can add you own shortcodes, filters and tags.

Learn how to develop themes by reading the [Theme API](api/themes).