Skip to content

docs(extensions): add example gallery #688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benvinegar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(extensions): add example gallery #688

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/silly-loops-act.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,9 +230,9 @@ export default function (hunk: HunkExtensionAPI) {
```

See [docs/extensions.md](docs/extensions.md) for the full API, the trust model,
and the `[extensions]` / `[extension.<id>]` config reference. Installable examples
include [review triage](examples/extensions/review-triage/) and an optional
[rendered Markdown file view](examples/extensions/rendered-markdown/).
and the `[extensions]` / `[extension.<id>]` config reference. The
[extension example gallery](examples/extensions/) includes review triage,
rendered Markdown, a minimal JSX file view, and three realistic file-view demos.

### OpenTUI component

Expand Down
21 changes: 9 additions & 12 deletions docs/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1332,21 +1332,18 @@ raised before the UI has mounted are buffered and flushed once it does, so a
Record a diagnostic line. Logs are collected per extension rather than written
to the terminal, because the TUI owns the screen.

## A complete example
## Complete examples

The examples directory contains two user-installable folder extensions:
The [extension example gallery](../examples/extensions/) contains four opt-in folder extensions:

- [`examples/extensions/review-triage/`](../examples/extensions/review-triage/)
is a session-local hunk triage board combining a sidebar, commands, dialogs,
lifecycle listeners, and the extension event bus. Its API evaluation and
follow-up opportunities are recorded in
[Extension API field notes](extension-api-evaluation.md).
- [`examples/extensions/rendered-markdown/`](../examples/extensions/rendered-markdown/)
parses Markdown into generic host-owned file-view rows. Its README shows how
to run it from the checkout or copy it into the global extensions directory.
- [`review-triage`](../examples/extensions/review-triage/) combines a React sidebar, commands, dialogs, navigation, lifecycle listeners, and the extension event bus.
- [`rendered-markdown`](../examples/extensions/rendered-markdown/) parses Markdown into host-owned file-view rows with source bindings and inline notes.
- [`jsx-file-view`](../examples/extensions/jsx-file-view/) is the smallest hook-using fixed-row React/OpenTUI file view.
- [`jsx-file-view-gallery`](../examples/extensions/jsx-file-view-gallery/) adds TypeScript change-atlas cards, CSS color swatches, dependency-version deltas, and a mixed raw/custom review.

Collapse lockfiles and generated output out of every review, and say how many
files were hidden.
The gallery also points to Hunk's bundled sidebar and VCS backends as production reference implementations. Review triage's API evaluation and follow-up opportunities are recorded in [Extension API field notes](extension-api-evaluation.md).

For a small single-file extension, collapse generated output out of every review and report how many files were hidden.

```ts
// ~/.config/hunk/extensions/collapse-generated.ts
Expand Down
2 changes: 2 additions & 0 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ Each folder tells a small review story and includes the exact command to run fro

## Installable extension examples

Browse the [extension example gallery](extensions/) for API coverage, exact run commands, and reference implementations.

- [`extensions/review-triage/`](extensions/review-triage/) adds a session-local hunk triage sidebar.
- [`extensions/rendered-markdown/`](extensions/rendered-markdown/) adds an optional parsed Markdown file presentation.
- [`extensions/jsx-file-view/`](extensions/jsx-file-view/) is the smallest hook-using fixed-row JSX proof of concept.
Expand Down
25 changes: 25 additions & 0 deletions examples/extensions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Extension examples

Ready-to-run, opt-in examples for Hunk's experimental TypeScript extension API. None of these folders are bundled or loaded automatically.

| Example | What it demonstrates | Best starting point for |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| [`review-triage/`](review-triage/) | A session-local hunk review board built from a React sidebar, commands, dialogs, navigation, lifecycle events, and the extension event bus | Stateful review workflows and custom sidebars |
| [`rendered-markdown/`](rendered-markdown/) | A parsed Markdown presentation using symbolic rows, exact-source bindings, inline notes, and raw-diff fallback | Host-rendered file previews |
| [`jsx-file-view/`](jsx-file-view/) | The smallest fixed-height React/OpenTUI file-view proof of concept, including hooks, semantic theme props, and row fallback | Custom JSX rows |
| [`jsx-file-view-gallery/`](jsx-file-view-gallery/) | TypeScript change-atlas cards, CSS color swatches, dependency-version deltas, and a mixed raw/custom five-file review | Realistic file-view layouts and fallback behavior |

Each folder has its own README with an exact command and notes on the API contract it exercises. Run an example directly from this checkout with `--extension` while developing. To install one, copy its complete folder into `~/.config/hunk/extensions/` and install any dependency its `package.json` declares.

@greptile-apps greptile-apps Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Exact-command promise is inaccurate

The gallery promises an exact command in every linked README, but the rendered-Markdown command references before.md and after.md, which are absent from the checkout. Following that example therefore does not provide the advertised runnable scenario; point it at included fixtures or identify the arguments as user-supplied files.

Knowledge Base Used: Extension System: API, Loading, and Host Integration

Prompt To Fix With AI 
This is a comment left during a code review.
Path: examples/extensions/README.md
Line: 12

Comment:
**Exact-command promise is inaccurate**

The gallery promises an exact command in every linked README, but the rendered-Markdown command references `before.md` and `after.md`, which are absent from the checkout. Following that example therefore does not provide the advertised runnable scenario; point it at included fixtures or identify the arguments as user-supplied files.

**Knowledge Base Used:** [Extension System: API, Loading, and Host Integration](https://app.greptile.com/modem/-/custom-context/knowledge-base/modem-dev/hunk/-/docs/extension-system.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.


## Reference implementations

Hunk also exercises the public API in its bundled extensions:

- [`src/extensions/default/ui/sidebar/`](../../src/extensions/default/ui/sidebar/) implements Hunk's built-in file navigation as a registered React sidebar.
- [`src/extensions/default/vcs/`](../../src/extensions/default/vcs/) implements the Git, Jujutsu, and Sapling backends as registered VCS adapters.

These are production reference implementations rather than installable examples. They remain loaded when user extensions are disabled.

## Learn the API

Start with the [extension authoring guide](../../docs/extensions.md), then use the focused website guides for [custom sidebars](https://hunkdiff.dev/docs/extend/custom-sidebars/), [file previews](https://hunkdiff.dev/docs/extend/file-previews/), and [VCS adapters](https://hunkdiff.dev/docs/extend/vcs-adapters/).

@greptile-apps greptile-apps Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Use the canonical website origin

These three links use hunkdiff.dev, while the website configuration and deployment documentation consistently use hunk.dev; readers are therefore sent through an origin that is not maintained as part of the documented website deployment.

Suggested change
Start with the [extension authoring guide](../../docs/extensions.md), then use the focused website guides for [custom sidebars](https://hunkdiff.dev/docs/extend/custom-sidebars/), [file previews](https://hunkdiff.dev/docs/extend/file-previews/), and [VCS adapters](https://hunkdiff.dev/docs/extend/vcs-adapters/).
Start with the [extension authoring guide](../../docs/extensions.md), then use the focused website guides for [custom sidebars](https://hunk.dev/docs/extend/custom-sidebars/), [file previews](https://hunk.dev/docs/extend/file-previews/), and [VCS adapters](https://hunk.dev/docs/extend/vcs-adapters/).
Prompt To Fix With AI 
This is a comment left during a code review.
Path: examples/extensions/README.md
Line: 25

Comment:
**Use the canonical website origin**

These three links use `hunkdiff.dev`, while the website configuration and deployment documentation consistently use `hunk.dev`; readers are therefore sent through an origin that is not maintained as part of the documented website deployment.

```suggestion
Start with the [extension authoring guide](../../docs/extensions.md), then use the focused website guides for [custom sidebars](https://hunk.dev/docs/extend/custom-sidebars/), [file previews](https://hunk.dev/docs/extend/file-previews/), and [VCS adapters](https://hunk.dev/docs/extend/vcs-adapters/).
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

4 changes: 3 additions & 1 deletion website/src/content/docs/docs/extend/custom-sidebars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ title: Custom sidebars
description: Render your own React sidebar view inside Hunk, with selection, scrolling, and event-driven state.
---

`hunk.registerSidebarView(view)` contributes a sidebar view — your own React component, rendered inside Hunk's OpenTUI tree. Registration is additive: your view exists beside the built-in file navigation, on either side of the review stream, and any number of views can be open at once. Pair it with [`registerCommand`](/docs/extend/extension-api/#hunkregistercommandcommand-handler) so a key opens it:
`hunk.registerSidebarView(view)` contributes a sidebar view — your own React component, rendered inside Hunk's OpenTUI tree. Registration is additive: your view exists beside the built-in file navigation, on either side of the review stream, and any number of views can be open at once. Pair it with [`registerCommand`](/docs/extend/extension-api/#hunkregistercommandcommand-handler) so a key opens it.

For a complete installable example, [review triage](https://github.com/modem-dev/hunk/tree/main/examples/extensions/review-triage) combines a right sidebar with hunk navigation, commands, dialogs, lifecycle events, and session-local state. The smallest standalone sidebar looks like this:

```tsx
// ~/.config/hunk/extensions/flat-sidebar.tsx
Expand Down
13 changes: 12 additions & 1 deletion website/src/content/docs/docs/extend/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,18 @@ some_key = "some value"

`[extensions] enabled` layers like every other option (repo config overrides user config); `--no-extensions` is a hard off switch no config layer can re-enable. `[extension.<id>]` tables pass through to the extension uninterpreted — see [`hunk.config`](/docs/extend/extension-api/#hunkconfig) for the merge rules and their caveats.

## A complete example
## Example gallery

The repository's [extension example gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions) collects four opt-in folder extensions:

- [Review triage](https://github.com/modem-dev/hunk/tree/main/examples/extensions/review-triage) combines a React sidebar, commands, dialogs, navigation, lifecycle events, and the extension event bus.
- [Rendered Markdown](https://github.com/modem-dev/hunk/tree/main/examples/extensions/rendered-markdown) builds a host-rendered file preview with exact-source bindings and inline notes.
- [JSX file view](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view) is the smallest fixed-height React/OpenTUI row example.
- [JSX file-view gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view-gallery) includes TypeScript, CSS color, dependency-version, and mixed-review demos.

Each README includes an exact command. The examples are not bundled or loaded automatically.

## A single-file example

Collapse lockfiles and generated output out of every review, and say how many files were hidden.

Expand Down
2 changes: 2 additions & 0 deletions website/src/content/docs/docs/extend/file-previews.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,8 @@ A `null`, invalid, oversized, cancelled, timed-out, or throwing layout produces

## Examples

Browse the complete [extension example gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions), or jump directly to a file-view example:

- [Rendered Markdown](https://github.com/modem-dev/hunk/tree/main/examples/extensions/rendered-markdown) is an installable symbolic-row preview with exact-source bindings and inline notes.
- [JSX file view](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view) demonstrates fixed-height React/OpenTUI rows.
- [JSX file-view gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view-gallery) includes TypeScript, CSS color, package dependency, and mixed raw/custom review examples.
Expand Down
Loading