Dimer

Dimer command line to write and publish docs with style.

Here we discuss technical aspects of Dimer along with Why it was created. We recommend reading the official docs to get started with Dimer.

💁 Official docs ➞

Why Dimer was created?

There are a handful of static site generators ranging from Jekyll to VuePress. They all work well in what they do but are too generic and flexible in what they output. On the other hand, Dimer is very strict with its use cases (you can only create documentation websites with it).

In brief, I wanted a tool, which needs almost zero configuration and outputs a website tailored for technical documentation. It must have:

1. Inbuilt search.
2. Option to create multiple versions of docs.
3. Easy to build/integrate custom website design (since I want my sites to have their own identity).

Do you think React or Vue would have become as powerful as they are, without the existence of REST API or JSON?

One of the best things happened to web/app development was the introduction of JSON. By separating backend and frontend, we can focus on one thing at a time and create these modern looking web apps.

Dimer takes the same approach and acts as a JSON API server for your Docs. When you run dimer serve, it compiles your markdown files and serves them as an API over HTTP.

You can consume this API to create:

1. Documentation websites.
2. Or a book (as PDF).

Features

All of the following features are supported out of the box by Dimer and requires minimal or no configuration.

1. Language agnostic CLI. You can use dimer on any major operating system, without installing any specific programming language.
2. Inbuilt search built on top of lunrjs.
3. Support for multiple versions of documentation.
4. Image detection.
5. Extended markdown.
6. 100% JAM stack.

Here's a zoomed out view of Dimer

Language agnostic CLI

It doesn't matter, whether you are Rubyist or write code in Php or Python. Dimer works with no additional dependencies on Windows, Mac and Linux.

Multiple versions of documentation

Projects that supports older versions like Ember, AdonisJs or Laravel do need documentation for these versions.

Dimer supports multiple versions as a first-class citizen. You can define a directory for each version of docs inside the config.

Image detection

When writing documentation, you can reference images from anywhere on your computer. Dimer will detect them inside your markdown and will store them to be served by the API server. It is how it works under the hood.

1. Dimer detects the image reference in Markdown.
2. If the reference is not an absolute HTTP URL, then it will be processed.
3. When processing the file, a thumbnail will be generated for progressive image loading.
4. Files are saved inside dist/__assets directory.
5. Image references are updated inside the generated JSON files.

Extended Markdown

Markdown is an excellent language for writing docs. Its simplicity comes the tremendous speed at which you can write. However, the kind of elements markdown can create limited.

Dimer enhances markdown with the help of macros to add new vocabulary to markdown. For example:

[note]
This is a note
[/note]

[tip]
This is a tip
[/tip]

[youtube url="https://youtu.be/dWO9uP_VJV8"]

[codepen url="https://codepen.io/eduardosada/pen/MbNZLX"]

Here's the complete syntax guide

Extensions

The CLI supports extensions written in Javascript. The extensions can listen for multiple events and can perform different tasks.

{
  "compilerOptions": {
    "extensions": ["extensions/addMacros.js"]
  }
}

The extensions array accepts paths to the Javascript files. The path can be an absolute path or relative path from the project root.

extensions/addMacros.js

module.exports = function (hooks, commandName) {
  hooks.before('compile', function ({ config, Markdown }) {
    Markdown.addMacro('button', macroCallback)
  })
}

Following is the list of hooks exposed by Dimer CLI.

| Hook | Lifecycle | Data | Description | |-------|----------|------|-------------| | compile | before | {config, Markdown} | The parsed copy of config and Markdown class is passed | | compile | after | {} | Nothing is passed in after compile hook | | doc | before | { doc, zoneSlug, versionNo, path} | The parsed doc along with zone, version and it's absolute path on disk is passed | | doc | after | ^ | Same data as the before hook |

Packages

The following are the first party packages used to build dimer.

| Package | Purpose | |----------|----------| | @dimerapp/markdown | Compiles markdown to JSON or HTML | | @dimerapp/dfile | File sandbox to compile it down to JSON and also report errors (if any).| | @dimerapp/datastore | Creates the JSON files to act as a database | | @dimerapp/fs-client | Compiles a tree of documents for all the versions defined inside the config file. Comes with an opinionated watcher too.| | @dimerapp/context | Context passed to all other packages to reduce the number of arguments | | @dimerapp/config-parser | Parses dimer.json file and report errors (if any) | @dimerapp/utils | Handy utils to keep all packages DRY. | | @dimerapp/cli-utils | Utilities for command line styles. | | @dimerapp/http-server | HTTP server to serve files generated by @dimerapp/datastore as JSON API. | | @dimerapp/image | Processes images detected inside markdown files via image detection feature. |

Also special thanks to following packages. Creating Dimer was impossible without them.

1. unified
2. chokidar
3. fs-extra
4. oclif