Skip to content

feature: add a figure block for standalone images, captions, and cross-references #479

@chaoxu

Description

@chaoxu

Summary

Add a real figure block for standalone images, captions, labels, and future figure-level metadata.

Right now the format spec only has inline image syntax:

  • FORMAT.md:48![alt](src)

That is fine for lightweight inline images, but it is the wrong semantic shape for figures that need captions, numbering, layout controls, and cross-references.

Motivation

Standalone images usually behave like document blocks, not inline phrasing content.
A block form would make it possible to support:

  • captions
  • #fig:... labels
  • figure numbering
  • cross-references like [@fig:...]
  • future figure metadata such as width/alignment/source attribution
  • multiple images in one figure later if needed

Proposal

Keep plain ![alt](src) for simple inline usage, but add a block-level figure form for richer semantics.

A natural fit for Coflat is the existing fenced-div plugin architecture. For example:

::: {.figure #fig:architecture}
![Architecture](img/arch.png)

System architecture overview.
:::

Expected behavior

  • Inline ![alt](src) remains supported.
  • A standalone figure block renders as a block container.
  • Caption text is editable as normal document content.
  • Labels participate in numbering and cross-reference resolution.
  • Rich/read/source behavior should stay coherent like other block plugins.

Why separate this from plain images

Treating every image as a block would make inline image usage awkward.
The better split is:

  • inline image syntax for lightweight inline media
  • figure block for semantic document figures

Relevant context

Current format/spec only documents inline images and block tables/code/etc. There is no figure-level construct yet.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions