---
weight: 2
description: "Get started with Limedocs in no time and create your documentation website from markdown files"
keywords:
  - Limedocs
  - HTML website
  - documentation
  - static website
---

# Getting Started

{% subtitle %}

Pimp your documentation in no time!

{% endsubtitle %}

This getting started guide lets you quickly setup a static website using **markdown** files as a source.


## Install Limedocs

{% alert %}

You will need either [Node.js](https://nodejs.org) (version 8 and superior) **or**
[Docker](https://www.docker.com/community-edition/) installed on your system. Windows users, please use the Docker image for now.

{% endalert %}

```bash title="Using npm"
# install globally using npm
$ npm install -g @limedocs/cli
# you can now use the limedocs CLI
$ limedocs -v
```

```bash title="Using Docker"
# Pull the image
$ docker pull limedocs/cli
# Then use `docker-run` which will run the `limedocs` executable
$ docker run --rm -ti limedocs/cli -v
```

## Create a new site

Simply run the `create site` command to create your new site. Limedocs will use its default *starter* (`@limedocs/starter-default`)
as an example. You can also use [another starter](starters) available by providing its URL.


```bash title="Using npm"
# This will create all directory tree in ./my-super-site
$ limedocs create site my-super-site
```

```bash title="Using Docker"
# This will create all directory tree in ./my-super-site
$ docker run -v `pwd`:`pwd` -w `pwd` --rm -ti limedocs/cli create site ./my-super-site
```

<br>Use the `dev` command to live edit your site without the hassle of setting up a server or hitting <kbd>F5</kbd>.

```shell title="Using npm"
$ cd my-super-site/
$ limedocs dev
```

```shell title="Using Docker"
$ cd my-super-site/
$ docker run -v `pwd`:`pwd` -w `pwd` --rm -p 8889:8889 -ti limedocs/cli dev
```


&rarr; Go to [http://localhost:8889](http://localhost:8889) to watch the result!


## Organize your content

Let's take a look at your site structure:

```
my-super-site/
  ├── limedocs-config.js
  ├── content/
  ├── archetypes/
  └── theme/
```

- `limedocs-config.js` is the main config file for your website (mandatory)
- `content/`is where your put all your pages (mandatory)
- `archetypes/` is where you put your site archetypes (optional)
- `theme/` is where you can put template files would would like to override as well as your static folder for your assets files (images, css, javascript, etc) (optional)


The `content` folder reflects your site structure: it contains `sections` and `pages`.

### Pages

A page is a document that will be rendered in your final website. A page consists of:
- a **path** (that uniquely defines the page)
- a **content** (for example, markdown content)
- some **metadata**: some key/value pairs defining various aspects of your page (for example, extracted from front-matter block in markdown)


### Sections

Sections let you group pages in logical groups. Section reflects your site directory tree and so can be nested.

Limedocs automatically build sections from:
- root directories within the `content` folder which contains a `_index.md` file
- then each nested directories that contains a `_index.md` file

If a sub-directory does not contain a `_index.md` file, pages within this directory will be attached
to the upper section. Lets see how this works:

```yaml
my-doc-website/
  └── content/
      ├── features
      │   ├── _index.md # Make "features" a section
      │   ├── awesome-feature.md # page within the section
      │   └── super-feature.md # another page
      ├── index.md # your homepage
      └── how-to # Warn: this is NOT a section as it does not contain a _index.md file
          ├── index.md        # these 3 pages will be ignored
          ├── how-to-walk.md
          └── how-to-run.md
```

{% alert type="warning" title="Warning about root directories" %}

Root directories should always contain `_index.md` files to be considered as sections, otherwise nested directories
within them won't be indexed.

{% endalert %}


### Other folders

#### Archetypes

Archetypes are content files in the `archetypes` folder of your project that contain preconfigured **front matter** for your website’s **content types**.
Archetypes are optional but facilitate consistent metadata across your website content and allow you to quickly generate instances of a content type via the `limedocs create page` command.
See [Archetypes](content-management/archetypes.md) for more.

#### Theme

The `theme` folder is where you can override some of the theme files your are using. This is where you put your `static` folder as well. See [Themes](themes) for more.


## Create your first new page

Of course you could you can use your favride editor to create a new markdown file, but the [Limedocs CLI](usage/cli.md) `create page` command will help you benefit from [archetypes](content-management/archetypes.md). Let's try it:

```bash
$ cd my-doc-website
$ limedocs create page content/first-section/article-2.md
```