# File System View An interactive, collapsible file system tree inside any Obsidian note. Like [Dataview](https://github.com/blacksmithgu/obsidian-dataview), but for files and folders **anywhere on your Mac** — not just inside your vault. > **Desktop only.** Requires Obsidian 1.4+. Uses Node.js and Electron APIs. --- ## What it does Write a fenced code block tagged `fsview`, point it at any folder on your machine, and fsview renders a live collapsible tree of matching files and folders with clickable links that open them in Finder. ````markdown ```fsview path: ~/Documents/Projects type: folders recursive: true sort: name ``` ```` **Clicking ▶ / ▼** → expand or collapse a folder inline. **Clicking a folder name** → opens it in Finder. **Clicking a file name** → reveals it highlighted in Finder. **Clicking the header path** → opens the root folder in Finder. Folders are loaded **lazily** — only scanned when you expand them. Pointing at large directories like `~/` is safe and instant. `path` can also point directly at a single **file**, in which case fsview renders just that file instead of a listing: ````markdown ```fsview path: ~/Documents/Projeto/file.extension ``` ```` --- ## Inline mentions Any path written as inline code that starts with `~/` or `/` and actually exists on disk is turned into a clickable mention — no code block needed: ```markdown See `~/Documents/Projeto/file.extension` for details. ``` Clicking it opens the folder (or reveals the file) in Finder, same as the code block. Paths that don't exist are left as plain inline code. Works in both Reading View and Live Preview — move your cursor into it to edit the raw path. --- ## Installation ### From the Community Plugin browser 1. Open Obsidian → **Settings → Community Plugins → Browse** 2. Search for **fsview** 3. Click **Install**, then **Enable** ### Manual installation 1. Download the latest release and unzip it. 2. Copy the `obsidian-fsview` folder into your vault's plugin directory: ``` /.obsidian/plugins/fsview/ ``` The folder must contain `main.js` and `manifest.json`. 3. Open Obsidian → **Settings → Community Plugins** → enable **fsview**. ### Build from source ```bash cd obsidian-fsview npm install npm run build ``` --- ## Options reference All options are `key: value` pairs inside the code block, one per line. | Key | Values | Default | Description | |-------------|-----------------------------------------------|----------|-------------------------------------------------------------------------------| | `path` | Any absolute or `~/…` path | — | **Required.** The directory to scan, or a single file to display. | | `type` | `all` · `files` · `folders` | `all` | Which entries count as leaves — folders stay visible either way so you can navigate into them. `folders` hides all files; `files` shows both. | | `recursive` | `true` · `false` | `false` | Allow expanding subfolders. | | `depth` | Integer | `0` / ∞ | Maximum expandable depth. Overrides `recursive`. | | `sort` | `name` · `modified` · `created` · `size` | `name` | Sort field. Applied per level — siblings are sorted independently. | | `order` | `asc` · `desc` | `asc` | Sort direction. | | `group` | `true` · `false` | Global setting (`true`) | Keep folders together above files, regardless of `sort`. | | `ext` | `.pdf, .fig, .sketch` | — | Filter files by extension (comma-separated). Folders are exempt so you can browse into them. | | `pattern` | Any regex string | — | Filter files by filename, case-insensitive. Folders are exempt so you can browse into them. | | `collapsed` | `true` · `false` | Global setting (`true`) | Start folders collapsed (lazy) instead of pre-expanded. | | `limit` | Integer | `500` | Maximum entries shown per expanded folder. | | `hidden` | `true` · `false` | `false` | Include hidden files/folders (those starting with `.`). | --- ## Examples ### Collapsible folder tree, all subfolders ````markdown ```fsview path: ~/Work/Clients type: folders recursive: true sort: name ``` ```` ### Start collapsed — expand only what you need ````markdown ```fsview path: ~/Work/Clients recursive: true collapsed: true ``` ```` ### Most recently modified files, newest first ````markdown ```fsview path: ~/Desktop recursive: true sort: modified order: desc limit: 50 ``` ```` ### Figma and PDF files only ````markdown ```fsview path: ~/Documents recursive: true ext: .fig, .pdf sort: modified order: desc ``` ```` ### Files matching a naming pattern ````markdown ```fsview path: ~/Documents/Finance pattern: ^Invoice ext: .pdf sort: created order: desc limit: 20 ``` ```` ### Two levels deep, everything visible ````markdown ```fsview path: ~/Projects type: all depth: 2 sort: modified order: desc ``` ```` --- ## Tree behavior - Folders always appear **before files**, for every sort field — turn it off per block with `group: false`. - Sorting is applied **per level** — siblings within the same parent are sorted independently. - Folders are **lazily loaded**: a directory is only scanned the first time you expand it. Re-expanding is instant (result is cached in the DOM). - Expand/collapse state is in-memory per render. Switching notes and returning resets to the default state. --- ## Global settings Go to **Settings → fsview** to configure defaults for all blocks: | Setting | Description | |----------------------|--------------------------------------------------------------| | Recursive by default | Allow expanding subfolders unless overridden per block | | Show hidden files | Include dotfiles globally | | Max results | Default cap on entries per expanded folder (overridable with `limit`) | | Start collapsed | Render all folders collapsed by default unless overridden per block | | Group folders before files | Keep folders above files regardless of sort field, unless overridden per block | --- ## Notes - `sort: created` uses `birthtime`, falling back to `mtime` on file systems that don't track creation time. - Results are read at render time. Switch notes and return to refresh. - Symlinks are stat'd but not recursed into. - Paths with spaces and special characters (including iCloud paths) are fully supported. --- ## License [MIT](LICENSE)