docmodel show menu hide menu

Getting Started

Please note: this guide assumes you already have Node.js and npm installed. If not, you should install Node.js before proceeding.

Install

We're going to use npm to install the docmodel command line tool. We'll use the -g flag to install the tool globally--this will add the executable to your system path / environment variables, so you'll be able to run the tool from any location. Open a terminal and run:

npm install -g docmodel-cli

To confirm the tool has been successfully installed, run:

docmodel -h

The docmodel help file will be printed.

Create Your First Project

Create a new directory for your project:

mkdir my-project

Move your terminal into the project directory:

cd my-project

Initialize a new project in the directory:

docmodel --init

Create Your First Document

To create your first document, create a new markdown file in the documents folder of your new project. We'll assume this document has been named getting-started.md. Next, open up your project's docmodel.json file. The default contents from a new project will be:

{
  "documents"       : {}, 
  "outdir"          : null, 
  "latest_version"  : null, 
  "site_navigation" : null,
  "index"           : null,
  "prev_next"       : null,
  "theme"           : {
    "name"          : "default",
    "strings"       : {},
    "client_options": {
      "sidebar_toc" : true
    }
  }
}

Add a key: value pair to the documents object where the key is the name of your document (as it will appear in navigation links), and the value is the path to your markdown document (relative to your project's documents folder). Your finished file should look something like:

{
  "documents": {
    "Getting Started": "getting-started.md"
  },
  "outdir"          : null, 
  "latest_version"  : null, 
  "site_navigation" : null,
  "index"           : null,
  "prev_next"       : null,
  "theme"           : {
    "name"          : "default",
    "strings"       : {},
    "client_options": {
      "sidebar_toc" : true
    }
  }
}

Bake and Serve

It's time to compile and run your project for the first time. From your project directory, run:

docmodel --bake --serve

This will launch the project in your default browser. You haven't added an index yet, so you'll have to click through some directory indexes to view your documents. Don't worry, we'll get to adding indexes and landing pages shortly.

Add More Documents

To add more documents, create the relevant markdown files and add more keys to the documents object:

{
  "documents": {
    "Getting Started": "getting-started.md", 
    "Something Else" : "something-else.md"
  },
  "outdir"          : null, 
  "latest_version"  : null, 
  "site_navigation" : null,
  "index"           : null,
  "prev_next"       : null,
  "theme"           : {
    "name"          : "default",
    "strings"       : {},
    "client_options": {
      "sidebar_toc" : true
    }
  }
}

You can add sections by making the value of a key another object. These can be nested:

{
  "documents": {
    "Getting Started": "getting-started.md", 
    "Something Else" : "something-else.md", 
    "A Section": {
      "Foo"             : "foo.md",
      "Bar"             : "bar.md",
      "A Nested Section": {
        "Baz": "baz.md"
      }
    }
  },
  "outdir"          : null, 
  "latest_version"  : null, 
  "site_navigation" : null,
  "index"           : null,
  "prev_next"       : null,
  "theme"           : {
    "name"          : "default",
    "strings"       : {},
    "client_options": {
      "sidebar_toc" : true
    }
  }
}

To save you having to run the bake and serve commands every time you make a change to the project, you can add a watch the initial time you run the command. This will automatically re-bake the project in full each time you make a change in the project directory:

docmodel --bake --serve --watch

You may notice there are no landing pages for your sections. Don't worry, we'll get to that later.

« PreviousNext »