{"id":16335007,"url":"https://github.com/lucperkins/jelly","last_synced_at":"2025-03-22T23:32:16.154Z","repository":{"id":75187295,"uuid":"558893852","full_name":"lucperkins/jelly","owner":"lucperkins","description":"A next-generation tool for building technical documentation sites","archived":false,"fork":false,"pushed_at":"2024-04-15T02:12:16.000Z","size":394,"stargazers_count":13,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-02T02:13:13.844Z","etag":null,"topics":["docs","documentation","markdown","rust","ssg","static","techdocs"],"latest_commit_sha":null,"homepage":"https://jelly.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucperkins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-28T14:35:47.000Z","updated_at":"2024-06-04T03:51:41.927Z","dependencies_parsed_at":"2023-11-18T23:23:05.186Z","dependency_job_id":"37dadb5c-77ac-4a13-bb4f-9fde430f1a10","html_url":"https://github.com/lucperkins/jelly","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucperkins%2Fjelly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucperkins%2Fjelly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucperkins%2Fjelly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucperkins%2Fjelly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucperkins","download_url":"https://codeload.github.com/lucperkins/jelly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245036112,"owners_count":20550662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","documentation","markdown","rust","ssg","static","techdocs"],"created_at":"2024-10-10T23:39:49.710Z","updated_at":"2025-03-22T23:32:15.825Z","avatar_url":"https://github.com/lucperkins.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jelly 🍓\n\n[![GitHub Actions status](https://github.com/lucperkins/jelly/actions/workflows/ci.yml/badge.svg)](https://github.com/lucperkins/jelly/actions)\n\n\u003e **Note**: Jelly is being built according to [README-driven development][rdd], whereby the README comes first and development follows.\n\u003e Although I'm actively working on it, very little of what's described in the README has come to fruition.\n\nJelly is a next-generation tool for building technical documentation sites for software projects.\nWhat makes it next gen?\n\n- **Lean**.\n  No JavaScript, no `package.json`, no `node_modules`.\n  Just a single static binary written in [Rust] that does everything.\n- Built-in **content management**.\n  Point Jelly at nested directories of properly formed [Markdown] (and some other supported inputs) and it builds site navigation, taxonomies, and more.\n- Built-in **best practices**.\n  Prose linting à la [Vale], link checking, SEO metadata, and more.\n- Robust **search**.\n  Use local site search or generate JSON search indices for popular platforms like [Algolia] and [Elasticsearch][es].\n- **Scalable**.\n  Use Jelly to build a single project or federate many projects together under a single [realm](#realms).\n- **Extensible**.\n  Though Jelly strives to cover most use cases out of the box, it also provides a powerful [extension mechanism](#extensions) to cover the remaining ground.\n- **Beautiful**.\n  Docs should never be ugly.\n  Jelly comes with a variety of lovely built-in components, configurable themes, and dark mode.\n\nJelly offers you **fewer choices**, **more guardrails**, and **just enough configurability** to cover a huge chunk of use cases with little fuss.\nIt's the result of a decade of experience\u0026mdash;and a not-inconsiderate amount of toil\u0026mdash;documenting software projects small and large.\n\n## Installation\n\nYou can install Jelly on macOS or Linux using [Homebrew]:\n\n```shell\nbrew install jelly\n```\n\nYou can also run Jelly using [Nix]:\n\n```shell\nnix run \"https://flakehub.com/f/lucperkins/jelly/0.1.206.tar.gz\"\n```\n\n## Create a new project\n\nTo fire up a starter project to experiment with:\n\n```shell\njelly init my-docs-project \u0026\u0026 cd my-docs-project\n```\n\nWhat you'll find in the project:\n\n- A `jelly.yaml` config file in the root\n- A `docs` directory with some sample [Markdown] docs nested several directories deep\n- An `api` directory with an [OpenAPI] specification\n\nAnd that's it!\nNothing else is needed to build your site.\n\n## Run the project locally\n\nTo run the site in dev mode:\n\n```shell\njelly dev\n```\n\nOpen your browser to http://localhost:3000 to see your running site!\nNavigate to http://localhost:3000/docs to see the landing page for the documentation or to http://localhost:3000/api to see rendered [OpenAPI] docs.\n\n## Build the project\n\n```shell\njelly build\n```\n\nThis generates the full static site in the `dist` directory.\nBecause the site is static, Jelly-built sites can be published on just about any platform.\n\n## Configuration\n\nAll configuration for Jelly is handled in the `jelly.yaml` file in the project root.\nThe table below shows the available parameters.\n\n| Parameter          | Meaning                                                     | Required | Default   |\n| :----------------- | :---------------------------------------------------------- | :------- | :-------- |\n| `title`            | The site title                                              | ✅       |           |\n| `description`      | A brief description of the site                             | ❌       |           |\n| `repo`             | The URL of the repository for the project                   | ❌       |           |\n| `colors.primary`   | The primary color for the theme                             | ❌       | `#123456` |\n| `colors.secondary` | The secondary color for the theme                           | ❌       | `#654321` |\n| `search`           | Search setup. Options are `local`, `algolia`, and `elastic` | ❌       | `local`   |\n\n## Markdown components\n\nJelly provides numerous Markdown components out of the box:\n\n- Everything you expect from rich code blocks: syntax highlighting for numerous languages, copy code button upon hover, optional metadata like filename, optional line numbers, higlighted lines, and even annotations.\n- Admonition blocks (info, success, warning, danger, tip, bug, note, etc.).\n- Collapsible callout blocks (with open/closed status persisted in localStorage).\n- Per-page edit and view source buttons.\n- Hoverable tooltips for key terms.\n\nYou can also create [custom components](#extensions).\n\n## Concepts\n\nJelly aims to be straightforward but there are two concepts worth familiarizing yourself with.\n\n### Extensions\n\nJelly enables you to extend its core functionality in several ways:\n\n1. Overwrite existing templates. Provide your own `templates` directory and any `.html` file in it overwrites one of the built-ins (such as `page.html`, `toc.html`, or `nav.html`).\n2. Provide extension **bundles**.\n   Bundles are collections of files\u0026mdash;JavaScript, CSS, etc.\u0026mdash;inside a directory that can be inserted into Jelly sites.\n   A bundle is any directory with a `jelly-bundle.yaml` file at the root that specifies what to include in it.\n   You can use directories on your machine as bundles or target remote [Git] repositories.\n3. Custom Markdown components.\n   Jelly uses [MDX] syntax for custom components (though it doesn't actually implement MDX).\n   Jelly passes arguments from those components to [TypeScript] functions that you can include in an extension bundle.\n\nThe Jelly CLI makes it easy to create and develop extensions:\n\n```shell\njelly extension create my-extension \u0026\u0026 cd my-extension\n\n# Create JS, CSS, and other files\n\njelly extension test\n```\n\n#### Built-in extensions\n\nJelly currently ships with a few built-ins:\n\n| Plugin    | What it does                                                                        |\n| :-------- | :---------------------------------------------------------------------------------- |\n| `mermaid` | Use [Mermaid] diagrams inside your [Markdown] content                               |\n| `openapi` | Transforms [OpenAPI] specifications in [YAML] into beautiful rendered documentation |\n| `cli`     | Generate docs for command-line tools from structured YAML sources                   |\n\n### Realms\n\nSometimes you need to expand beyond a single docs project and create many projects tied together.\nFor that, Jelly offers **realms**, which group an indefinite number of projects together.\nRealms are coordinated by a central server that keeps track of which projects exist, handles things like global search, and more.\n\nYou can create a realm by running a Jelly server:\n\n```shell\njelly serve-realm\n```\n\nJelly sites can join the realm by adding a `realm` parameter in `jelly.yaml` specifying the address of the server.\n\n```yaml\nrealm: https://my-jelly-server.com\n```\n\nIf you specify a realm, you can publish your site whenever you make changes:\n\n```shell\njelly publish\n```\n\nWhen 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).\n\nUsing realms has two key benefits:\n\n- You can toggle the site's search bar between local (in-project) and global (cross-project) search.\n- Each realm server produces a single (highly customizable) landing page providing information and links to all projects.\n\nIn general, realms are intended largely for organizations with many documentation projects and software ecosystems with many closely related projects.\n\n[algolia]: https://algolia.com\n[es]: https://github.com/elastic/elasticsearch\n[git]: https://git-scm.com\n[homebrew]: https://brew.sh\n[markdown]: https://markdownguide.org\n[mermaid]: https://mermaid-js.github.io\n[mdx]: https://mdxjs.com\n[nix]: https://zero-to-nix.com\n[openapi]: https://openapis.org\n[rdd]: https://tom.preston-werner.com/2010/08/23/readme-driven-development\n[rust]: https://rust-lang.org\n[typescript]: https://typescriptlang.org\n[vale]: https://vale.sh\n[yaml]: https://yaml.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucperkins%2Fjelly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucperkins%2Fjelly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucperkins%2Fjelly/lists"}