Getting Started

Pimp your documentation in no time!

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

Install Limedocs

Note

You will need either Node.js (version 8 and superior) or Docker installed on your system. Windows users, please use the Docker image for now.

# install globally using npm
$ npm install -g @limedocs/cli
# you can now use the limedocs CLI
$ limedocs -v
# 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 available by providing its URL.

# This will create all directory tree in ./my-super-site
$ limedocs create site my-super-site
# 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


Use the dev command to live edit your site without the hassle of setting up a server or hitting F5.

$ cd my-super-site/
$ limedocs dev
$ cd my-super-site/
$ docker run -v `pwd`:`pwd` -w `pwd` --rm -p 8889:8889 -ti limedocs/cli dev

→ Go to 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:

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
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.

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 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 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 create page command will help you benefit from archetypes. Let's try it:

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

Edit this page / submit change