@dimerapp/cli
Simplest way to publish docs
Last updated 6 months ago by virk .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @dimerapp/cli 
SYNC missed versions from official npm registry.
Dimer App

Dimer is an open source project and CMS to help you publish your documentation online.


We believe every project/product is incomplete without documentation.
We want to help you publish user facing documentation, without worrying about tools or code to write.


Dimer

Dimer command line to write and publish docs with style.

oclif-image travis-image appveyor-image npm-image

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

Current Tags

  • 1.0.12                                ...           latest (6 months ago)

13 Versions

  • 1.0.12                                ...           6 months ago
  • 1.0.11                                ...           9 months ago
  • 1.0.10                                ...           10 months ago
  • 1.0.9                                ...           a year ago
  • 1.0.8                                ...           a year ago
  • 1.0.7                                ...           a year ago
  • 1.0.6                                ...           a year ago
  • 1.0.5                                ...           a year ago
  • 1.0.4                                ...           a year ago
  • 1.0.3                                ...           a year ago
  • 1.0.2                                ...           a year ago
  • 1.0.1                                ...           a year ago
  • 1.0.0                                ...           a year ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 27
Dev Dependencies (20)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |