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 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.
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:
- Inbuilt search.
- Option to create multiple versions of docs.
- 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:
- Documentation websites.
- Or a book (as PDF).
All of the following features are supported out of the box by Dimer and requires minimal or no configuration.
- Language agnostic CLI. You can use dimer on any major operating system, without installing any specific programming language.
- Inbuilt search built on top of lunrjs.
- Support for multiple versions of documentation.
- Image detection.
- Extended markdown.
- 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
Dimer supports multiple versions as a first-class citizen. You can define a directory for each version of docs inside the
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.
- Dimer detects the image reference in Markdown.
- If the reference is not an absolute HTTP URL, then it will be processed.
- When processing the file, a thumbnail will be generated for progressive image loading.
- Files are saved inside
- Image references are updated inside the generated JSON files.
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]
Here's the complete syntax guide
path can be an absolute path or relative path from the project root.
Following is the list of hooks exposed by Dimer CLI.
||The parsed copy of config and Markdown class is passed|
||Nothing is passed in after compile hook|
|doc||after||^||Same data as the before hook|
The following are the first party packages used to build dimer.
|@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/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/image||Processes images detected inside markdown files via image detection feature.|
Also special thanks to following packages. Creating Dimer was impossible without them.