Obsidian MatterViz

A lightweight Obsidian plugin for rendering supported materials science files directly inside Obsidian markdown documents.

Overview

Obsidian MatterViz is a materials visualization plugin built to render supported scientific files inside Obsidian markdown embeds. The main workflow is to place a supported file in a note, render it inline, and inspect the structure or spectra without leaving Obsidian.

The plugin focuses on a few core workflows:

• inline rendering of structure, trajectory etc. (similar as MatterViz) inside markdown notes
• additional band structure and DOS visualization for electronic workflows
• single-file rendering for supported inputs without needing extra setup
• small, practical UI controls that stay close to the data

Usage

Step-by-Step

1. Pick a supported file type from the table below.
2. Wrap the content in a fenced code block using the matching keyword.
3. Paste the block into any Obsidian note.
4. MatterViz will render the content inline, directly inside the note.

Example

```poscar
Cubic BN
3.57
0.00000000 0.50000000 0.50000000
0.50000000 0.00000000 0.50000000
0.50000000 0.50000000 0.00000000
B N
1 1
Selective dynamics
Cartesian
0.00000000 0.00000000 0.00000000 T T F
0.25000000 0.25000000 0.25000000 F F F
Cartesian
0.01000000 0.01000000 0.01000000
0.00000000 0.00000000 0.00000000
```

Supported File Types and Inline Keywords

Category	File / Example	Fence keyword(s)
Structure (VASP)	POSCAR / CONTCAR	poscar, vasp
Structure (CIF)	.cif / .mcif / .mmcif	cif, mcif, mmcif
Structure (XYZ)	.xyz / .extxyz	xyz, extxyz
Structure (other)	.pdb / .mol / .mol2 / .sdf	pdb, mol, mol2, sdf
LAMMPS / plain text	LAMMPS data, dump, .lmp	lmp, data, dump
Trajectories	.traj, .h5, .hdf5, .dcd, .xtc, .trr, .lammpstrj	traj, h5, hdf5, dcd, xtc, trr, lammpstrj
Volumetric (cube)	.cube	cube
Volumetric (VASP)	CHGCAR / ELFCAR / PARCHG	chgcar
Fermi / DOS / BXSF	.bxsf / .frmsf / DOSCAR	bxsf, frmsf, doscar
Vasprun (bands/DOS)	vasprun.xml	vasprun
Generic aliases	content-based hints / generic pastes	crystal, structure, matterviz

Installation

Step-by-Step Guide

1. Open a terminal or PowerShell window in the folder where you want to keep the project.
2. Clone the repository:

git clone https://github.com/aritraroy24/obsidian-matterviz.git

3. Move into the project folder:

cd obsidian-matterviz

4. Install the dependencies:

npm install

5. Build the plugin so the runtime files are generated using the following command:

npm run build

6. Open your Obsidian vault folder on disk.
7. Create a folder at .obsidian/plugins/obsidian-matterviz/ if it does not already exist.
8. Copy generated dist/ folder, manifest.json, main.js and styles.css files into that folder.
9. Restart Obsidian.
10. Go to Settings > Community plugins and enable Obsidian MatterViz.
11. Open a note and paste a supported fenced block such as poscar, cif, or traj with the appropriate content to verify it renders inline.

Typical Folder Layout

Obsidian Vault/
└── .obsidian/
    └── plugins/
        └── obsidian-matterviz/
            ├── dist/
            ├── manifest.json
            ├── main.js
            └── styles.css

Screenshot of Rendered Views

KPOINTS Notes

• If a same-folder KPOINTS file exists, MatterViz uses it for symmetry labels. The filename of the vasprun xml is used to find the corresponding KPOINTS file (e.g. vasprun.xml looks for KPOINTS, vasprun_band.xml looks for KPOINTS_band etc.).
• If not, the band structure still renders, but labels may fall back to inferred placeholders.

Shoutout and Credit

Special shoutout to the authors of MatterViz, Janosh Riebesell and Matthew Evans, for creating the original MatterViz library that powers this plugin:

• Repository: https://github.com/janosh/matterviz

If you use this project in academic work, please cite MatterViz:

@software{riebesell_matterviz_2022,
  title = {matterviz: visualization toolkit for materials informatics},
  author = {Riebesell, Janosh and Evans, Matthew},
  date = {2026-01-23},
  year = {2026},
  doi = {10.5281/zenodo.17094509},
  url = {https://github.com/janosh/matterviz},
  note = {10.5281/zenodo.17094509 - https://github.com/janosh/matterviz},
  urldate = {2026-01-23},
  version = {0.3.1},
}

Contact

Author: Aritra Roy

• 🌐 Website: aritraroy.live
• 📧 Email: contact@aritraroy.live
• 🐙 GitHub: @aritraroy24
• 𝕏 Twitter: @aritraroy24

Project Links:

• GitHub Repository: obsidian-matterviz
• Issues: GitHub Issues