README file from
GithubXnotes 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
- If you have the compiled ZIP, extract the
xnotes-embedsfolder into your vault's.obsidian/plugins/directory. You can also build the plugin from source. - In Obsidian, open Settings → Community plugins and enable Xnotes Embeds. If it is missing from the list, reopen the vault.
- Copy a
.xnotefile 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
.xnotewikilink 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
.xnotenotebooks 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.