AutoGallery

by Jasper Hwang
5
4
3
2
1
Score: 50/100

Description

Automatic image layout for Obsidian.

Reviews

No reviews yet.

Stats

0
stars
120
downloads
0
forks
10
days
1
days
1
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
21
commits

Latest Version

a day ago

Changelog

AutoGallery 1.0.4 — automatic image layout for Obsidian.

简介

AutoGallery 处理 Obsidian 笔记里的图片排版:连续图片自动排成等高画廊,单图按比例取宽并支持文字绕排,裁剪只记录比例,PDF 导出与阅读视图保持一致。

它不改写 Markdown 图片链接,也不写入像素尺寸;效果来自图片说明里的 ag: 参数与可导出的布局模板。停用插件后,笔记仍按原生方式显示。

  • 画廊 — 相邻图片自动成行,支持拆行、锁定、行高上限与五种拖拽手柄。
  • 单图 — 按比例取宽,左右浮动绕排,拖拽调整宽度,对齐箭头与一键重置。
  • 图注与裁剪 — 十个 ag: 参数、按比例裁剪、嵌套作用域与图注对话框。
  • 模板与路由 — 可复用的布局模板、导入/导出与 frontmatter 路由。
  • PDF 导出 — 纸张感知分页、版式与分页预览、页边距与页码(仅桌面端)。

本次更新内容

1.0.4

  • 修复 Live Preview 中图注偏低的问题:图片行以两个空格结尾(Markdown 硬换行)时,行尾空格会在图片下方多撑出一个行盒,图注因此下移一整行。现在这些空格不再参与布局,源码内容不受影响。
  • 画廊行的图注间距为 12px,单图行使用配置的图注间距(默认 6px);阅读视图行为保持不变。
  • 重新生成文档断言台账:check:docs 8/8 通过,0 条错误。

Overview

AutoGallery handles image layout in Obsidian notes: consecutive images form equal-height gallery rows, single images take a ratio-based width with text wrapping, crops store only a ratio, and PDF export matches the reading view.

It never rewrites Markdown image links or writes pixel sizes; every effect comes from ag: parameters in the image caption and exportable layout profiles. Disable the plugin and the note renders natively again.

  • Galleries — adjacent images form rows, with row splitting, locking, row-height ceilings and five kinds of handles.
  • Single images — ratio-based width, left/right floats with text wrapping, drag to resize, alignment arrows and one-click reset.
  • Captions and crops — ten ag: parameters, ratio-based crops, nested scopes and a caption dialog.
  • Templates and routing — reusable layout profiles, import/export and frontmatter routes.
  • PDF export — paper-aware pagination, layout and paginated previews, margins and page numbers (desktop only).

What's changed

1.0.4

  • Fixed a Live Preview issue where the caption sat one blank line below the picture when an image line ended with two spaces (a Markdown hard break): those trailing spaces formed an extra line box under the block-level image. They no longer take part in layout, and the note's source is untouched.
  • Gallery captions keep their 12px seam; single images use the configured caption gap (6px by default). The reading view is unchanged.
  • Regenerated the documentation claim ledger: check:docs passes 8 / 8 with 0 findings.

安装 / Install — download main.js and manifest.json below into <vault>/.obsidian/plugins/obsidian-autogallery/.

文档 / Documentation — 中文 · English · Home

示例库 / Demo vaults — 中文示例库 · English demo vault

README file from

Github

Overview

AutoGallery handles image layout in Obsidian notes: consecutive images become rows, single images take their width from their aspect ratio, text can wrap around them, crops are stored as ratios, and PDF export follows the reading view.

It never rewrites Markdown image links or stores pixel dimensions. Layout comes from parameters in the image caption and from exportable layout templates. Disable the plugin and the note renders natively again.

  • Built for illustrated notes, portfolios, tutorials and documents meant to be printed.
  • Not a pixel-level canvas or an image editor.

Install

Requires Obsidian 1.5 or newer; desktop and mobile share the same build.

  1. Community plugins (after listing): Settings → Community plugins → turn off Safe mode → Browse → search AutoGallery → Install and enable.
  2. Manual: download main.js and manifest.json from Releases, place them in the plugin folder, then restart Obsidian.
<vault>/.obsidian/plugins/obsidian-autogallery/
  main.js
  manifest.json

These two files are all that is needed; there is no styles.css. Once enabled, an AutoGallery section appears in Settings, and two or three consecutive image lines should become one gallery row.

Community install · Manual install

Quick start

Three image lines with no blank lines between them become one row of equal height. A blank line ends the gallery.

![[photo-01.jpg]]
![[photo-02.jpg]]
![[photo-03.jpg]]

Two images side by side get a taller row, so details stay readable:

![[photo-04.jpg]]
![[photo-05.jpg]]

Three operations cover most edits:

  • Give one image its own row: separate it with body text or a heading, or write ag:isolate.
  • Set images per row: write ag:rows=2,2 on the first image of the group.
  • Change a single image's width: drag its bottom-right grip in Live Preview; ag:width is written on release.

Full tutorial: Quick start · Three common operations

Five core concepts

  1. Grouping reads the source, not the screen: Grouping rules
  2. Two or more adjacent images are always a gallery: Row splitting
  3. A single image gets its width from its ratio: Width routing
  4. The closer the declaration, the higher the priority: image parameters > template > global settings; Annotation syntax
  5. The container decides what is possible: lists, tables and callouts behave differently; Nested scopes

Full explanation: Five core concepts

Capability map

Grouped by workflow; each group maps to one section of the documentation.

Galleries — consecutive images form rows; ag:rows splits them and ag:group locks a row; row-height ceilings and orphan images; five kinds of handle. Grouping · Row splitting · Height and orphans · Gallery handles

Single images — automatic width from ratio; left/right floats and text wrapping; drag to resize, align with arrows, reset in one click. Width routing · Float and wrap · Resize, align, reset

Annotations and crops — ten ag: parameters; crop any region by ratio; scope rules for lists, tables and callouts; caption dialog and reset. Annotation syntax · Cropping · Nested scopes · Dialog and reset

Templates and routing — define a whole width rhythm with range rules; import/export templates; switch by frontmatter. Layout templates · Import and export · Frontmatter routing

PDF export — reflow to paper size; layout and paginated previews; margins, page numbers and pagination. Export dialog · Pagination · Troubleshooting

Reference — settings defaults; commands and entry points; compatibility; common misreadings. Settings · Commands · Compatibility · Pitfalls

Annotations and gestures

Parameters live in the image caption, separated by |. Omit them and automatic routing applies. Both standard Markdown and ![[...]] embeds work.

Parameter Common values Effect
ag:layout auto gallery float center Override automatic layout
ag:side left right center Alignment and float side
ag:width 10%–100% Width of an image or float unit
ag:crop + ag:top 16:9 + 0:50:0 Crop ratio and top-edge position
ag:rows / ag:group 3,2 / 7 Split rows / lock a row
ag:isolate / ag:exclude flag Cut grouping / hand back to Obsidian
![[cover.jpg|Cover|ag:side=center|ag:width=61%]]
![[chart.png|Chart|ag:crop=16:9|ag:top=0:50:0]]
![Standalone|ag:isolate](https://raw.githubusercontent.com/jh0531/obsidian-autogallery/HEAD/images/one.png)

All ten parameters: Annotation syntax.

Gestures (Live Preview)

  • Drag the bottom-right grip to resize; double-click to reset → Corner grip
  • Drag a divider to change column widths, or the bar under a row to change its height → Five handles
  • Use the side buttons to swap or merge, and the link button to lock a row → Locking a row
  • Use the arrows in the free space beside an image to change alignment → Alignment arrows

PDF export

Run Export PDF (AutoGallery) from the command palette, or export from the file context menu. The plugin renders in the main window, measures against the paper size, and paginates.

  • Two previews: layout preview shows continuous flow; paginated preview shows real page boundaries, margins, page numbers and heading breaks.
  • Controls: paper size, orientation, margin presets and mirrored margins, scale, header/footer page numbers.
  • Pagination: gallery rows never split, a single image can shrink to the page foot, headings can start a page, and trailing orphan lines are pulled back.

Export dialog · Pagination · Troubleshooting

Development

npm install
npm run build

The build output is main.js in the repository root. Copy it and manifest.json into a test vault at .obsidian/plugins/obsidian-autogallery/ and reload the plugin. There is no test script; static checks are npm run build, git diff --check and npm run check:docs.

The rendering pipeline and architectural constraints are in CONTRIBUTING-EN.md; design notes live in specifications/. Read the contributing guide before opening a pull request.

Credits

Full changes: Changelog; the complete map: Documentation map.

Support

If AutoGallery saves you time, you can support its development:

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for the full text.