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 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 โ
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.
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
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.
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.
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
dist/__assets
directory. - 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]
[youtube url="https://youtu.be/dWO9uP_VJV8"]
[codepen url="https://codepen.io/eduardosada/pen/MbNZLX"]
Here's the complete syntax guide
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 |
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.