Creating the first website

In this guide, we will use Dimer to publish Markdown files to a fully functional documentation website.

Prerequisites

Before getting started, make sure

  1. You have a Dimer account or create one.
  2. You are familiar with command line. We will be using Dimer CLI to publish documentation.
  3. Download Dimer CLI for your platform.

Creating a new project

Once you have the CLI installed for your operating system, you are ready to publish your first documentation website with Dimer.

Run dimer --version to make sure you are running version 1.0.6 or higher.

  • Create new project
  • Directory structure
Create new project
mkdir my-app-docs
cd my-app-docs

dimer init
Directory structure
├── dimer.json
└── docs
  └── master
    └── index.md
  1. The dimer init command will prompt you to choose a subdomain, you can feel free to skip it. However, a subdomain is required to publish your documentation.

  2. Also, it will create a dummy document inside docs/master directory. You can configure directory structure or even change subdomain using the dimer.json.

Publishing

The docs are published using dimer publish command. Below is the list of actions occurred when you run this command.

  1. Authenticate your account details.
  2. Create a website for you using the subdomain.
  3. Sync all versions defined inside the dimer.json file.
  4. Bundle all markdown files and publish them to the website.

Also, the dimer compiler will show you errors when it is unable to compile a markdown document successfully. Documents with error(s) are never published.

Compiler error

Dimer works on sane defaults. Which means, it will get your document in good shape, even when most of the details are missing. However, in few cases, getting defaults is impossible.

In the following screenshot. The compiler returned an error since the title for the document is missing.

We can fix this by defining a title as H1 or by setting it inside YAML front matter.

---
title: Document title
---

This is a sample markdown document to get you started with Dimer. Each document always contains a `title`, which can be in the form of `h1` or defined inside YAML front matter.

Or

# Document title

This is a sample markdown document to get you started with Dimer. Each document always contains a `title`, which can be in the form of `h1` or defined inside YAML front matter.

Compiler warnings

The warnings are raised, when compiler thinks your document can be improved. Documents with the warning(s) are published online.

In the following screenshot, a warning is raised, since we forgot to close the note macro.

Next steps

The art of publishing great documentation lies in how well you format your markdown files. Following guides will help you in mastering same.