---
title: "Configuration"
weight: 2
tocDepth: 5
---

# Configuring Limedocs

## Configuration file

Configuration must be placed in a `limedocs.config.js` file placed in your site directory, like this:

```bash
my-super-site/
  ├── limedocs.config.js # <-- this file
  ├── content/
  ├── archetypes/
  └── theme/
```

## Configuration properties

### Multilingual properties

#### Default language

Useful for multilingual websites, the `defaultLanguage` property defines the default language that will be displayed to visitors. Defaults to `en`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  defaultLanguage: "it"
  // ...
}
```
</details>

#### Available languages

For multilingual websites, the `languages` property can be used to specify what languages are available on your site. Defaults to `["en"]`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  languages: ["en", "it", "fr"]
  // ...
}
```
</details>

#### Mixing languages

For multilingual websites, the `mixLanguages` property can be used to mix languages, e.g link to pages written in `defaultLanguage` when no translations are available for a given page. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  mixLanguages: true
  // ...
}
```
</details>

***

### Server properties

#### Host

Specify the `host` to bind and listen to when using the `limedocs dev` or `limedocs serve` commands.
Defaults to `0.0.0.0`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  host: "127.0.0.1"
  // ...
}
```
</details>

#### Port

Specify `port` to bind and listen to when using the `limedocs dev` or `limedocs serve` commands.
Defaults to `8889`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  port: 8080
  // ...
}
```
</details>

#### Enable HTTPS

Use the `secure` property to enable HTTPS. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  secure: true
  // ...
}
```
</details>

***

### Rendering properties

#### Dot files

Use the `renderDotFiles` property to specify whether or not render filenames starting with a dot. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  renderDotFiles: true
  // ...
}
```
</details>

#### Drafts

Use the `renderDrafts` property to specify whether or not render documents marked as **draft**. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  renderDrafts: true
  // ...
}
```
</details>

#### Underscore files

Use the `renderUnderscoreFiles` property to specify whether or not render filenames starting with an underscore. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  renderUnderscoreFiles: true
  // ...
}
```
</details>

***

### Theme properties

Theme properties must be placed under the `themeConfig` object.

#### Menus

You can define one or more menus depending on the theme you're using. Menus does not necesseraly reflect your documentation tree: it can directly link to specific section, external locations, etc. Menus also support sub-menus. On this website, menus are used in the top navigation bar and in the footer.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    menus: {
      first: [ // a menu with id "first"
        {
          path: "quickstart" // path to a section
        },
        {
          url: "https://github.com", // external URL
          label: "Github project"
        },
      ],
      second: [ // a menu with id "second"
        {
          path: "quickstart/about.md", // path to a page
          label: "Github project",// override page title
        },
        {
          url: "https://npmjs.com",
          label: "NPM",
          menus: { // sub-menus
            platforms: [ // a sub-menu with id "platforms"
              {
                url: "https://docker.com",
                label: "Docker"
              },
              {
                url: "https://docker.com",
                label: "Docker"
              },

            ]
          }
        }
      ]
    }
    // ...
  }
  // ...
}
```
</details>


#### Navigation bar pages

`themeConfig.navShowPages` defines what kind of pages to show in navigation bar.

 - `all`: show all pages from all sections & child sections
 - `top-level-sections`: show pages from all top-level sections
 - `current-section`: : show pages from current section
 - `current-section-and-children`: : show pages from current section and its child sections

 Defaults to `top-level-sections`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    navShowPages: "current-section"
    // ...
  }
  // ...
}
```
</details>

#### HTML Meta-Tags

Use the `themeConfig.metaTags` `Array` property to specify HTML meta-tags objects to add to each page. Meta-tag objects can have the following properties:

* `name`:
Meta-tag name attribute. Can be one of *application-name*, *author*, *description*, *generator*, *keywords*, *viewport*.
* `charset`:
Meta-tag charset attribute.
* `http-equiv`:
Meta-tag http-equiv attribute.
* `content`:
Meta-tag content attribute.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    metaTags: [
      {
        name: "author",
        content: "John Doe"
      }
    ]
  }
  // ...
}
```
</details>

#### Theme

Use the `themeConfig.theme` property to specify theme to use (npm package name). Defaults to `@limedocs/theme-yuzu`. Package must be installed locally using `npm install my-package` within your site directory or globally (using `npm install -g`). Defaults to `@limedocs/theme-yuzu`.

<details open="true">
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    theme: "my-custom-theme"
  }
  // ...
}
```
</details>

#### Syntax highlighting theme

Use the `highlightTheme` property to specify syntax highlighting theme to use (from [highlight.js](https://github.com/highlightjs/highlight.js/tree/master/src/styles)). Defaults to `monokai-sublime`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    highlightTheme: "ocean"
  }
  // ...
}
```
</details>

#### Edit link

Use the `themeConfig.showEditLink` property to specify wether or not to show the edit-link. Defaults to `false`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    showEditLink: true
    // ...
  }
  // ...
}
```
</details>

#### Table of contents

Table Of Content depth can be specified using `tocDepth`. `Number` between 1 and 6. defaults to `4`.

<details>
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    tocDepth: 5
    // ...
  }
  // ...
}
```
</details>


#### Stylesheets

Additional stylesheets can be specified using the `stylesheets` array property.

<details open="true">
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    stylesheets: [
      "static/css/limedocs-override.css"
    ]
    // ...
  }
  // ...
}
```
</details>

#### Google Analytics

Google analytics tracking can be set up using `googleAnalytics` object containing the following properties:

- `enabled`: `Boolean` indicating whether or not to enable Google Analytics tracking.
- `trackingId`: Your GA tracking ID
- `secondaryTrackingId`: Your GA secondary tracking ID (*optional*)

<details open="true">
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  themeConfig: {
    googleAnalytics: {
      enabled: true,
      trackingId: "UA-XXXX",
      secondaryTrackingId: "UA-YYYY",
    }
  }
  // ...
}
```
</details>

***

### Other properties

#### Git repository

Git Repository informations can be specified using the `repository` containing the following properties:

* `branch`: Git branch to use. Defaults to `master`.
* `path`: Path to your site directory. Can be empty if your site resides at the root of your repository.
* `provider`: Can be `github`, `gitlab`, `bitbucket`, or `generic`. Defaults to `generic`.
* `url`: Git repository URL. Can be `ssh` or `https` URLs.

<details open="true">
    <summary>Example</summary>

```js title="limedocs.config.js"
module.exports = {
  // ...
  repository: {
    url: "https://github.com/developit/preact.git",
    path: "docs",
    provider: "github",
    branch: "master"
  }
  // ...
}
```
</details>

#### Base URL

Use the `url` propery to specify the base url of your website. Usually you will put this property within the [`env`](#using-multiple-environments) property so you can set different URLs for different environments. Defaults to `http://{host}:{port}`.

<details open="true">
    <summary>Example</summary>

```js title="Simple usage"
module.exports = {
  // ...
  url: "http://myadomain.com"
  // ...
}
```
```js title="Usage in env"
module.exports = {
  // ...
  env: {
    development: {
      url: "http://localhost:8889/"
      // ...
    },
    production: {
      url: "http://mydomain.com/"
      // ...
    }
  }
}
```
</details>


## Using multiple environments

You may want to specify properties based on the environment. This can be done in the `env` property.
Configuration values are thereby set dynamicaly based on the `LIMEDOCS_ENV` environment variable.

In the following example, the `url` value will be set to:

- `http://localhost:8889/` when `LIMEDOCS_ENV` is set to *"development"*.
- `http://mydomain.com/path/to/site/` when `LIMEDOCS_ENV` is set to *"production"*.


**Example**

```js title="limedocs.config.js"
module.exports = {
  // ...
  env: {
    development: {
      url: "http://localhost:8889/"
      // ... more properties
    },
    production: {
      url: "http://mydomain.com/path/to/site/"
      // ... more properties
    },
    staging: {
      url: "http://mydomain.com/path/to/site/"
      // ... more properties
    }
  }
  // ...
}
```

You can have a unlimited number of environments of any name.