A next-generation tool for building technical documentation sites
Note: Jelly is being built according to README-driven development, whereby the README comes first and development follows. Although I'm actively working on it, very little of what's described in the README has come to fruition.
Jelly is a next-generation tool for building technical documentation sites for software projects. What makes it next gen?
package.json
, no node_modules
.Jelly offers you fewer choices, more guardrails, and just enough configurability to cover a huge chunk of use cases with little fuss. It's the result of a decade of experience—and a not-inconsiderate amount of toil—documenting software projects small and large.
You can install Jelly on macOS or Linux using Homebrew:
brew install jelly
You can also run Jelly using Nix:
nix run "https://flakehub.com/f/lucperkins/jelly/0.1.206.tar.gz"
To fire up a starter project to experiment with:
jelly init my-docs-project && cd my-docs-project
What you'll find in the project:
jelly.yaml
config file in the rootdocs
directory with some sample Markdown docs nested several directories deepapi
directory with an OpenAPI specificationAnd that's it! Nothing else is needed to build your site.
To run the site in dev mode:
jelly dev
Open your browser to http://localhost:3000 to see your running site! Navigate to http://localhost:3000/docs to see the landing page for the documentation or to http://localhost:3000/api to see rendered OpenAPI docs.
jelly build
This generates the full static site in the dist
directory.
Because the site is static, Jelly-built sites can be published on just about any platform.
All configuration for Jelly is handled in the jelly.yaml
file in the project root.
The table below shows the available parameters.
Parameter | Meaning | Required | Default |
---|---|---|---|
title |
The site title | ✅ | |
description |
A brief description of the site | ❌ | |
repo |
The URL of the repository for the project | ❌ | |
colors.primary |
The primary color for the theme | ❌ | #123456 |
colors.secondary |
The secondary color for the theme | ❌ | #654321 |
search |
Search setup. Options are local , algolia , and elastic
|
❌ | local |
Jelly provides numerous Markdown components out of the box:
You can also create custom components.
Jelly aims to be straightforward but there are two concepts worth familiarizing yourself with.
Jelly enables you to extend its core functionality in several ways:
templates
directory and any .html
file in it overwrites one of the built-ins (such as page.html
, toc.html
, or nav.html
).jelly-bundle.yaml
file at the root that specifies what to include in it.The Jelly CLI makes it easy to create and develop extensions:
jelly extension create my-extension && cd my-extension
# Create JS, CSS, and other files
jelly extension test
Jelly currently ships with a few built-ins:
Plugin | What it does |
---|---|
mermaid |
Use Mermaid diagrams inside your Markdown content |
openapi |
Transforms OpenAPI specifications in YAML into beautiful rendered documentation |
cli |
Generate docs for command-line tools from structured YAML sources |
Sometimes you need to expand beyond a single docs project and create many projects tied together. For that, Jelly offers realms, which group an indefinite number of projects together. Realms are coordinated by a central server that keeps track of which projects exist, handles things like global search, and more.
You can create a realm by running a Jelly server:
jelly serve-realm
Jelly sites can join the realm by adding a realm
parameter in jelly.yaml
specifying the address of the server.
realm: https://my-jelly-server.com
If you specify a realm, you can publish your site whenever you make changes:
jelly publish
When you publish, you coordinate with the central server, pushing any information upstream that the server needs to provide cross-project functionality (mostly search index information).
Using realms has two key benefits:
In general, realms are intended largely for organizations with many documentation projects and software ecosystems with many closely related projects.