Xnotes Embeds

by Jeany
5
4
3
2
1
Score: 50/100

Description

Obsidian plugin designed to view and cite Xnote-formatted notes.

Reviews

No reviews yet.

Stats

1
stars
16
downloads
0
forks
4
days
4
days
4
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
4
commits

Latest Version

4 days ago

Changelog

Fixes

  • Declare the CodeMirror dependencies used by Live Preview and link previews.
  • Use Obsidian's DOM helpers and window-scoped timers for pop-out compatibility.
  • Validate stroke coordinates and pressure before rendering.
  • Simplify citation syntax checks and preserve ZIP path validation, including rejection of control characters.

Verification

The official Obsidian ESLint plugin reported no warnings locally, and all 16 automated tests passed. On macOS, embeds and hover previews were verified in Reading View and Live Preview, along with citation creation and rendering in a pop-out window.

README file from

Github

Xnotes Embeds

Open Xnotes notebooks in Obsidian. Embed a page, crop to a drawing, or link to a specific sheet from your Markdown notes.

Quick start · Markdown examples · Viewer controls · Build from source · Compatibility

Read Embed Cite
Open a .xnote file from the file explorer or a wikilink. Show the full page, automatically fit its content, or select a region. Insert a link and preview into Markdown, with adjustable width and alignment.

The plugin reads and renders notebooks locally. It opens .xnote files in read-only mode and saves citations as Markdown in your vault.

Quick start

  1. If you have the compiled ZIP, extract the xnotes-embeds folder into your vault's .obsidian/plugins/ directory. You can also build the plugin from source.
  2. In Obsidian, open Settings → Community plugins and enable Xnotes Embeds. If it is missing from the list, reopen the vault.
  3. Copy a .xnote file into your vault. Open it from the file explorer, or embed it in a Markdown note using the examples below.

Markdown examples

Replace notes/notebook.xnote with the path to a notebook in your vault.

Markdown Result
[[notes/notebook.xnote]] Opens the notebook.
![[notes/notebook.xnote]] Embeds the full first page.
![[notes/notebook.xnote#page=2]] Embeds page 2 in full.
![[notes/notebook.xnote#crop=auto]] Fits the first page to its visible content. &crop=auto also works.
![[notes/notebook.xnote#page=2&crop=auto]] Fits page 2 to its visible content.
![[notes/notebook.xnote#page=2&crop=auto&width=60&align=center]] Embeds the cropped page at 60% of the available width and centers it. You can also use width and align on their own.

[!TIP] In Live Preview, put each direct embed on its own line. Hold Ctrl or Cmd and hover over an ordinary .xnote wikilink to see a floating preview in Reading View or Live Preview. Click the link in Reading View, or use Ctrl or Cmd + click in the editor, to open the referenced page.

If a linked notebook is missing, Xnotes Embeds displays a notice.

Manual crop and layout

Use an xnote block when you want to specify the crop as coordinates.

file: notes/notebook.xnote
page: 2
crop: 0.10, 0.35, 0.45, 0.25
width: 60%
align: center
Field Meaning
file Notebook path relative to the vault root. In generated citations, the companion Markdown note supplies the path.
page Page number, starting at 1. Defaults to the first page.
crop Use auto to fit visible content, four numbers for a manual crop, or omit it for the full page. A manual crop uses x, y, width, height, expressed as fractions of the page between 0 and 1.
width Image width from 1% to 200% of the available space. Defaults to 100%. Above 100%, the preview scrolls horizontally.
align left, center, or right. Defaults to left.
hash and id Fields generated by the plugin to locate the original page by its content and identify the citation during updates.

Crops retain the paper color and template within the visible area. An automatic crop of a blank page displays the whole sheet.

Viewer controls

The plugin interface currently uses Spanish labels. The table lists the labels you'll see in Obsidian.

Control What it does
Anterior / Siguiente Goes to the previous or next page.
− / + Zooms in or out in 25 percentage-point steps, between 25% and 400%.
Ajustar Resets zoom to 100% and fits the page to the viewer width.
Insertar página Creates a citation showing the full page.
Insertar contenido Creates a citation that fits the visible strokes, shapes, and images with a margin. Available when the page has visible content.
Seleccionar recorte Turns on region selection. Drag over an area to cite it, or click the control again to exit selection.
Copiar enlace Saves a full-page citation and copies its wikilink to the clipboard.
Ancho (%) / Alineación Sets the preview's width and left, center, or right alignment in the citation dialog. Alignment applies when the image fits the available width.
Insertar cita / Copiar enlace / Enter Confirms the title and performs the selected action in the citation dialog.
Abrir página N Opens the page shown in an embed or preview.
Exportar SVG Saves a full-page SVG snapshot in the vault's attachment location for use in Canvas or another app.

Insert, edit, or repair a citation

Open the destination Markdown note first, then open the notebook and choose a citation control. Xnotes Embeds stores the citation in a companion Markdown note and inserts its link and preview into the last active Markdown note. It inserts at the cursor in editing mode, appends to a note that is closed or in Reading View, or copies the link and preview to the clipboard if no destination is available.

To resize an existing citation, follow its link and edit width or align in the companion note's xnote block. In Settings → Files and links, enable automatic link updates so Obsidian can update wikilinks when files move or are renamed.

If the cited page changes, disappears, or matches multiple pages, the preview offers these repair controls.

Control What it does
Elegir página de nuevo Lets you enter a replacement page number.
Actualizar cita y usar página completa Saves the replacement as a full-page preview.
Actualizar cita y ajustar al contenido Saves the replacement and keeps automatic cropping. This option appears for automatically cropped citations.
Volver a seleccionar recorte Opens the replacement page so you can draw a new region for the existing citation.
Cancelar actualización Exits selection and keeps the existing citation.

Build from source

Use Node.js 24 or later and run these commands from the repository root.

npm ci
npm run build
npm test

Copy the generated main.js and the repository's manifest.json and styles.css into .obsidian/plugins/xnotes-embeds/ in your vault. Enable the plugin as described in Quick start.

Command What it does
npm ci Installs the dependencies pinned in the lockfile.
npm run build Type-checks the source and compiles the plugin to main.js.
npm run dev Rebuilds when source files change. Reload the plugin in Obsidian to pick up the new build.
npm test Runs the automated tests. The integration test for the private notebook sample skips when that file is absent.

Compatibility

  • Supports paginated .xnote notebooks with a v1 manifest, pen strokes, basic shapes, PNG images, custom paper colors, built-in rulings, and a subset of notebook templates.
  • Pages keep their dimensions and colors. If a notebook omits the paper color, the viewer uses a light paper color because Xnotes may store the app-wide preference separately.
  • Ink rendering uses Xnotes' smoothing and pressure curve with approximate SVG outlines. The viewer displays a notice when it approximates an ink tool.
  • Annotated PDFs, rich text, infinite canvas, and complex transformations have limited support. The plugin was verified in Obsidian on macOS. Android testing is pending.

Credits

The decoder and parts of the renderer were checked against Xnotes v0.9.8. See NOTICE-XNOTES.txt for upstream attribution.

This plugin was developed with AI assistance from OpenAI Codex.