gaspar_schot / Supercharged Local Directory File Browser


Version: 5.0.2+4f913a2 updated

Summary: Makes file:/// directory ("Index of...") pages (and many server-generated index pages) actually useful. Adds sidebar and preview pane; keyboard navigation and sorting; media playback with shuffle, loop, and playlist (m3u) support; preview, edit, and save markdown/plain text files; preview images and fonts; grid views for images and fonts; user-defined bookmarks; more.



License: GPL-3.0-or-later

If you like this script, please consider making a donation or sending me a comment to let me know what you think. Thanks!

NOTE: This script was developed in the latest version of Vivaldi, running on Mac OS Mojave. It has been tested in Safari, Firefox, and various Chrome-based browsers, but it has been not been tested in any other browsers or OSes, and no effort has been made to ensure compatibility with older browsers. Please report any issues.


VERSION 5.0.2 (June 3, 2020): Lots of bug fixes.
ADDED: Experimental support for opening .webloc and .url files: select file in sidebar and use double-click, Cmd/Ctr-Return, or Cmd/Ctr-ArrowDown to load the link.
- Note: This is untested on Windows; please report any problems.
- Note: Behavior for link files located on remote servers can be unpredictable, depending on server configuration.
- Specifically, link files with .com, .org, or .net in their names (e.g., may not work.
FIXED & IMPROVED: Completely overhauled handling of invisible and ignored files and directories.
- (Ignored files are those which the browser typically cannot open natively, like common office or graphics files.)
- Added a new "Ignored Items" menu item with "Hide Ignored Items" and "Ignore Ignored Items" items.
- By default, ignored items are visible.
- If "Ignored Ignored Items" is checked (default), ignored items can be selected in the sidebar, but will not be downloaded. Uncheck it in order to restore the default browser behavior. It is recommended to leave the default setting unchanged.
- Visibility of items that are both invisible and ignored can be toggled with the "Show Invisibles" checkbox.
FIXED: Several problems with tabbing into previewed text documents.
FIXED: An issue with arrow key behaviour when the text editor was open.
FIXED: Various issues with keydown events in textareas and contenteditable elements.
FIXED: Main menu: toggling default text editor view wasn't working, and default settings weren't being honored; fixed some styling issues.
FIXED: Help window wasn't styled correctly.
FIXED: Long-standing issues with autoloading cover art. Many times the incorrect file was loaded; selection should be much more robust now.
- Image files with 'cover','front','album','jacket','sleeve','cd','disc','insert','liner','notes' in the title will be loaded first in that order, with exact matches having preference;
- Otherwise the first image found will be loaded.
- Note that there can be false positives because a file will be matched whenever there is no exact match and one of these words appears in an image name.
IMPROVED: Prevent annoying FOUC ("flash of unstyled content") when loading directories in content pane. This makes me happy.
IMPROVED: Also show loading spinner while directory preview is loading; if a directory is inaccessible (perhaps because its permissions deny browser access) the spinner will remain visible.
IMPROVED: Clicked link handling in HTML files. After clicking a same-origin link, the item will open in the preview pane; closing the item will return to original HTML file. Non-same-origin links will open in a new tab/window.
IMPROVED: When sidebar is focused, content pane directory previews will be dimmed.
IMPROVED: Allow tab key to focus links and form elements in previewed html documents (including text editor preview).
IMPROVED: Show/Hide Invisibles from focused content pane with Cmd/Ctr + I.
IMPROVED: Content pane title now updates correctly when navigating history state for directories or txt/html files.
ADDED: Warning when attempting to open local links from a non-local page from an html file.
CHANGED: "Show Ignored Files" pref default to "true" because it could be confusing when using the script for the first time if those items were invisible.
UPDATED: markdown-it.js > 11.0.0, markdown-it-multimd-table.js > 4.0.2.
Many more fixes and improvements.


  • FIXED: "Parent Directory" link in previewed directory header wasn't working.
  • IMPROVED: Better handling of links in previewed HTML pages. Some issues remain; will fix soon.

VERSION 5.0.0 is here! Finally! Lotsa stuff...


  • Converted most <table> HTML elements in the UI to flex box <divs>, because it's 2020....
  • Converted many "if ... else" conditional statements to "switch" statements for clarity and efficiency.
  • Converted css to selector-based system and pruned many unneeded styles. More work to be done....

IMPROVED: Significantly improved performance of initial directory processing; this is especially noticeable for directories with many items.


  • ADDED: Keyboard navigation for previewed directories.

    • Use Tab to toggle focus between sidebar and content pane (for images, fonts, grids, html and text files, and the text editor).
    • Use Escape to focus sidebar from content pane.
    • Use arrow keys to navigate items as in sidebar.
    • Use Cmd/Ctrl + ArrowUp to go to parent directory in content pane.
    • Previewed directories honor "show invisibles" and "ignore ignored files" pref.
  • ADDED: Double-click or ( Cmd/Ctr + Return ) items in previewed directories to open them.

  • ADDED: Continuous audio playback from previewed directories.

  • ADDED: Dark theme for directory preview.

  • ADDED: "Open in Content Pane" and "View Directory Source" links in sidebar footer.

    • "Open in Content Pane" will show the current directory in the content pane.
    • (This is useful in situations were the currently previewed directory contains only files and you want to navigate directories in the content pane.)
    • IMPROVED: Directory list now uses custom file icons for media files, because otherwise it's difficult to tell audio and video files apart.


  • FIXED: Clicking links in previewed html files didn't do anything. Now internal #links or same-origin links will open in the content pane; links to external sites will load in a new tab/window.


  • ADDED: Custom support for filelists: m3u files with links to directories and any kind of file supported by the script and browser.

  • ADDED: "Make Playlist" menu item. Download a basic (no timings) .m3u playlist of the media files in the current directory.

    • "Make Playlist" menu item has options for all files and directories, all non-media files, files only, and directories only.
    • You can also click the content pane title to show an m3u playlist entry for the selected file.
  • ADDED: Click audio player title to show an m3u playlist entry for the current media file.

  • IMPROVED: Added warning when opening a playlist with local files from a non-local page. Playlist will open, but local files will be disabled.


  • ADDED: New user pref to use light or dark theme for text editor instead of main UI theme.

    • Text editor theme can be toggled with new button in text editor toolbar.
  • ADDED: Keyboard shortcut to toggle text editor split view: Cmd/Ctrl + \ .

  • [IMPROVED: Text editor now remembers insertion/caret position or selection range (until page is reloaded or URL changes). Position and range are remembered even if you close the text editor and view other content in the current directory, or if you navigate to another directory from within the preview pane.] Not implemented yet.

  • IMPROVED: Better handling of unicode text.



    • Cmd|Ctrl + E : Toggle main menu.
    • Cmd|Ctrl + Shift + E : Show text editor.
  • ADDED: Cmd|Ctrl + \ : toggle sidebar.

  • IMPROVED: Escape now also closes menus.

  • IMPROVED: Allow normal Cmd|Ctrl + +/– behavior if no scalable content (images, grids, etc.) is visible; allows scaling of browser window contents.


  • FIXED & IMPROVED: Many style improvements and fixes.

    • Increased UI contrast overall.
    • Improved UI icon visibility.
    • File icons weren't visible in the preview titlebar in some circumstances.
  • ADDED: Keyboard navigation for the main menu.

    • Use Up/Down Arrows to select items, Left/Right Arrows to open submenus.
    • Return/Enter : Choose selected item.
  • ADDED: Toggle "Ignore ignored files" menu item.

  • ADDED: Basic Help menu item (shows keyboard shortcuts, etc.)

  • ADDED: More tooltips for various UI elements.

  • IMPROVED: Completely overhauled warnings html and styles.

  • IMPROVED: Added more info to stats in sidebar footer:

    • On hover, show total number of each kind of file or dir, and how many are hidden.
    • Live updates when show/hide invisibles or show/hide ignored files settings are changed.
    • Stats update when playlist is loaded.
  • IMPROVED: Tab key behavior; tab now also toggles focus of previewed images, font specimen text, and text editor, as well as html and .txt/.md files.

  • ADDED: Allow arrow keys to scroll scaled/zoomed images when focused.

  • FIXED: Allow sidebar arrow navigation when sidebar is hidden.

  • FIXED: Toggle media checkbox wasn't working.

  • FIXED: An issue with ?s in file names.

  • FIXED: Cmd|Ctrl + W now closes tab/window if no content is being previewed.

  • FIXED: Arrow navigation for sidebar and previewed directories sometimes used default arrow behavior, preventing proper scroll into view behavior.

  • IMPROVED: Workaround for Chrome bug with scroll into view multiple elements simultaneously (e.g., scrolling selected sidebar and grid items); scrolling is "instant" instead of "smooth."

  • CHANGED: "Ignore ignored files" pref behavior.

    • If "true", ignored files will be hidden. If "false", ignored files will be shown, but will not be downloaded when clicked or navigated to.
  • FIXED: Unchecked media files would be selected and played in some circumstances.

  • IMPROVED: Warn before closing previewed font files and playlists.

  • IMPROVED: Reloading previously-selected directory when navigating to parent folder now uses row id and so is not affected is the sort is changed.

  • IMPROVED: Directory list now remembers sort direction.

  • IMPROVED: HTTP error pages now load in the content pane and with original formatting.


  • FIXED: PDFs now load correctly if a pdf has already been loaded.
  • Various fixes for Firefox.
  • Choosing "Default User Settings" now does not remove history from query string.
  • Removed m3u from "Text" file types.
  • Many, many other fixes and improvements.


  • Chrome: Smooth scroll (for scrollIntoView() ) seems to be broken in the latest releases.

  • Firefox: Clicking media checkboxes (to toggle selection) causes page reload.

  • Firefox: Tabbing into previewed directories in content pane doesn't work; click in content pane instead in order to use arrow navigation.

More to come.

This script transforms the default local directory page (and many server-generated index pages) into a full-featured file browser, with a resizable sidebar and preview pane. (See screenshots below.)

If you like this script, please consider making a donation to encourage development. Thanks!


  • Resizable sidebar and directory/file preview pane.
  • Arrow navigation in sidebar:
    • Up and Down Arrows select next/prev item.
    • Left and Right Arrows select next/prev item of same type.
  • Navigate sidebar by typed string.
  • Show/Hide file details (size (if avail), date modified (if avail), kind, extension).
  • Sort sidebar items by name or file details.
    • Default sort = sort by name with folders on top.
  • Preview all file types supported by browser (html, text, images, pdf, audio, video) plus fonts.
  • Preview and edit markdown and plain text files.
  • Audio and video playback, with shuffle, loop, skip audio +/- 10 or 30 sec via keyboard.
    • Preview other files (e.g., lyrics or cover art) in same directory while playing audio.
    • User setting to autoload cover art (if any images in directory, load "cover.ext" or first image found)
  • Open m3u playlists.
  • Open fonts and view glyph repertoire.
    • Save glyphs as SVG.
  • Grid views for images and/or fonts with keyboard navigation.
  • User settings (see $settings in code; some settings can be changed via the main menu in the UI and will be remembered in URL query):
    • Light or Dark theme.
    • Bookmarks for local or remote directories.
    • Default image grid size.
    • Default UI font size and font-family.
    • Default UI font and font-size.
    • Default file sorting.
    • Sort with directories on top.
    • Treat apps as directories (MacOS and *nix only)
    • Show or hide invisible files.
    • Show or hide ignored files in the ignored files list (see $row_settings in code below $settings).
    • Show or hide file details.
    • Use custom file icons or browser defaults.
    • Autoload index.ext files.
    • Autoload cover art in directories with audio files.
    • Text editing default view: split, source, or preview.
    • Text editing sync scroll: on or off.


  • This script was developed in the latest version of Vivaldi, running on Mac OS Mojave. It has been tested in Safari, Firefox, and various Chrome-based browsers, but it has been not been tested in any other browsers or OSes, and no effort has been made to ensure compatibility with older browsers. Please report any issues.

  • After installing, you should look at the "User Settings" section in the code near the top of the script (ca. line 60). There you can edit the bookmark menus and set defaults for many UI features. There is additional information about each setting in the comments.

  • Userscripts will not run on file:/// urls by default, so for this script to work, you will have to enable it in your browser's extension settings (e.g.: For Tampermonkey in Chrome, go to Chrome the extension page, click the details button on the Tampermonkey pane and check 'Allow access to file URLs'). Safari does not allow local directories to be browsed, so the script will not work on local directories, but it will work on remote directories (or on local directories through a local server).

  • This script was developed primarily to work with local files. Because of security concerns, userscripts running in local files are not allowed to set cookies or use local storage. Therefore the User Settings must be hard-coded into the script, which means they will be overwritten every time the script is updated. To ease the inconvenience of this, you can export your settings from the main menu as a text file. However, many user settings can be changed in the UI and will be stored in the URL query string.

  • The script works on many server-generated index pages, too. Just add an @include line for each url at the top of the script.

KEYBINDINGS (These don't work in all browsers):

  • Arrow Up/Down: Select prev/next item.
    • If audio is playing, and prev/next file is also audio, it will be highlighted but not loaded in the audio player; press return to load it.
  • Arrow Left/Right: Select prev/next row of the same kind as the current selection.
    • If current selection is a media file, select and begin playback of the next media item.
  • Opt/Alt + Arrow Left/Right: Skip audio ±10s
  • Opt/Alt + Shift + Arrow Left/Right: Skip audio ±30s
  • Cmd/Ctrl + Arrow Up: Go to parent directory
  • Cmd/Ctrl + Arrow Down: Open selected directory
  • Return: Open selected directory, select file, or pause/play media.
  • Space: Pause/Play media files
  • Cmd/Ctrl + D: Toggle file details (size, date modified) in some index page types.
  • Cmd/Ctrl + G: Show or Reset Grid
  • Cmd/Ctrl + I: Toggle Invisibles
  • Cmd/Ctrl + Shift + O: Open selected item in new window/tab
  • Cmd/Ctrl + R: Reload grids and previewed content, reset scaled images/fonts, reset media files to beginning.
  • Cmd/Ctrl + W: Close previewed content (doesn't work in all browsers; use close button instead), or close window if no content is being previewed.
  • Cmd/Ctrl + Shift + < or >: Scale preview items and grids.


AFTER with dark theme and image grid
After with dark theme and image grid

AUDIO PLAYER with dark theme and cover art
Audio player with dark theme and cover art

MARKDOWN editing and preview
Markdown editing and preview

Light theme with image and font grid


FIXED, CHANGED, & IMPROVED: Image, font, and font glyph grids.

  • Added up/down arrow navigation. This is a change from the previous behavior, where up/down arrows always navigated the sidebar. This will also work if the grid is hidden after selecting an image or font glyph.
  • Also added arrow navigation for font glyphs, and :hover and selected styles.
  • Fixed a deeply-buried bug that prevented the selected grid item from scrolling into view with arrow navigation.
  • Fixed a stupid bug that prevented the first font in the directory from being included in the grid.
  • Fixed some problems with normal font file browsing after viewing font glyphs.
  • Improved styling for previewed and zoomed images. Known issue: scaled images aren't positioned properly.

FIXED and IMPROVED: Playlists.

  • Window title and sidebar head are now changed to indicate presence of playlist.
  • First track wasn't being selected when "autoload_media" = true.
  • Directory stats weren't being reset after closing a playlist.
  • Grid button and "show invisibles" checkbox are hidden with open playlist.

IMPROVED: Currently selected sidebar item will now scroll into view after various events, like sorting change, showing/hiding details, resizing sidebar, etc.
FIXED: Several menu items weren't working: Default User Settings, Export User settings, Contact, and Donate (that might explain a few things...).
FIXED: Document title didn't include entire path.
Many other small bug fixes and style tweaks, including some specifically for Firefox and Safari.

A few small fixes and style tweaks.

NEW: Basic support for media playlists (.m3u and .m3u8).

  • Added "Open Playlist..." item to the main menu.
  • Playlist items will replace the current directory items in the sidebar. Times (if available) will be displayed in the "size" column. "Default" sorting = original playlist sort.
  • Playlist can be closed via the "Close" button or shortcut, and the previous directory contents will be loaded.
  • Streaming links are not supported.
  • Beware of cross-origin limitations. For example, if your playlist includes locally-hosted media files, you will need to load it from a file:/// page in your browser.
  • For remote files, if you are using a javascript-blocker (like uMatrix or NoScript), you may have to allow scripts from the hosting site (e.g., in order for playback to work.

NEW: Open local fonts directly and view font information and complete glyph repertoire. (The previous ability to browse fonts in the directory list is unchanged.)

  • Added "Open Font..." item in the menu item.
  • View individual glyphs and save as SVG.

FIXED: Apps weren't being properly classified in the index.
FIXED: An issue with formatting the current directory name in the sidebar header.
IMPROVED: Refreshed UI colors and icons; added icons for more file types.
IMPROVED: Many styling adjustments, including setting numbers (for sizes and date, etc.) to tabular spacing.
CHANGED: Renamed "shortcuts" user setting to "bookmarks"; if you use exported settings, you'll have to change this in your code.
INTERNALS: Prettified and modularized some code. Removed some newly-unnecessary functions. Began to prune CSS. Updated markdown-it to 9.1.0.

FIXED: Really updated markdown-it and plugins.

FIXED: An issue with video display.
FIXED: Several styling issues in Firefox, including textarea in text editor not expanding to full window height.
FIXED: An issue with some servers that add a trailing '/' to the query string.
IMPROVED: Updated markdown-it to v9.0.1; also updated some markdown-it plugins.
NEWS: Version 4.1, with a new feature of interest to designers, is in development.

VERSION 4.0.5b
IMPROVED: Clicking "Parent Directory" link in previewed directories now remembers sorting and numbering prefs.
FIXED: Hopefully fixed close content behavior.
FIXED: Several bugs with sorting items by size.
FIXED: Various minor styling issues and tweaks.
Known issue: PDFs don't always display when selected; this seems to be an issue with Chrome. I will attempt to address this in future updates.

VERSION 4.0.4b Wrapping things up....
Known Issue: Close button function is buggy, particularly with Text Editor and Grids. Fixes coming.
FIXED: Left/Right arrow key navigation failed for video files
FIXED: Content preview title wasn't being set for autoloaded images.
FIXED: An issue with autoloading media and cover art when the first media file was a video.
FIXED: Various issues with parsing local directory indexes in Firefox.
FIXED: Various issues with parsing, calculating, and displaying file size and date-modified information.
IMPROVED: Attempted to make index-type detection and index prep more generic, so that the script will work with more sites "out of the box."
IMPROVED: Made index prep much more efficient, especially for table-type index pages and directories with many items.
IMPROVED: Better error handling for directories with certain percent-encoded characters in file names.
IMPROVED: Changed order of sorting headers to better align with sort data in list.
OTHER: More minor styling issues and improvements.
Please report any bugs or feature requests to mshroud AT
And please consider buying me a coffee (or just let me know what you think), if you find the script useful. Thanks!

VERSION 4.0.3b
ADDED: Preview current directory index source: click the double-caret icon in the sidebar stats footer to toggle preview. This is useful for server configurations that include information in addition to the index itself and is quicker than opening a separate "View source" tab.
FIXED: An issue with content display caused by the fix for pdf display in the previous version.
FIXED: Up directory navigation didn't correctly account for invisible files and directories when selecting previously selected directory.
FIXED: More issues with prepping "pre"-type index pages.
FIXED: Some issues with Error page display.
FIXED: Various minor styling issues.
CHANGED: Moved "Disable Text Editing" menu item to top level.
Many other small improvements and tweaks.

VERSION 4.0.2b
FIXED: Pdf display (I hope).

VERSION 4.0.1b
FIXED: Audio files weren't being loaded.
FIXED: Script would fail if a file name included a special regex character [\^$.|?*+().
FIXED: Various issues with parsing "pre"-type index pages.
IMPROVED: Sorting and display of items with names beginning with white spaces.
IMPROVED: More efficient and robust index type detection.
ADDED: Sorting for previewed directory contents. Initial sorting is the same as the parent's current sort pref.
ADDED: Custom icons and numbering for previewed directory contents; numbering reflects the parent's current numbering pref.
NOTE: There is an issue with Chrome browsers and pdf file display, so pdfs don't display reliably.
NOTE: Some further fixes and styles tweaks coming.

VERSION 4.0.0b:
Numerous additions, improvements, and massive internal changes. Virtually no line of code has been left untouched. "b" === "bugs" likely; updates will be forthcoming.
IMPORTANT: This version uses a new format for user settings in the code; you will have to re-enter your defaults manually after updating.
- Do NOT use exported settings from any earlier version of the script.
NEW: Added independent text editor pane.

  • Invoke with Cmd/Ctrl + E, or in main menu > Text Editing > Toggle Text Editor", or under "Show Details".
  • To prevent loss of work (and for convenience, e.g., to refer to a file while writing), previously entered text will not be cleared when the "New" button is clicked again, when the "Close" button is clicked, or when a sidebar item is selected.
  • Use the Save button to save the text as a text or html file, which can be previewed and edited as usual by navigating to its saved location.

ADDED: Option to number index items, with new user setting.
ADDED: Stats footer in sidebar showing dir and file count.
ADDED: Icons for shortcuts menu to indicate local vs. remote links.
ADDED: Text editing: Clear button to empty text editing pane.
CHANGED: Text editing: Github styling customizations: Make table cells top-aligned, darker blockquote text color.
IMPROVED: Text editing: When saving rendered HTML, header uplinks will be removed.
IMPROVED: Text editing: Don't close other previewed content when making new text editing pane.
IMPROVED: Text editing: Much improved warning system for edited text: now uses postMessage to communicate between iframe and parent.
IMPROVED: Content display: use the same code to prep and style directory contents in the preview pane.
IMPROVED: Live sorting of grid items (but images and fonts are still sorted separately).
IMPROVED: Image zoom positioned accurately under click.
IMPROVED: Better handling of 404 Errors (Page not found): server error message will appear in sidebar, warning icon in content pane.
IMPROVED: File URLs: If a file URL (instead of a directory) is entered directly in the browser URL bar, the parent directory will be loaded instead and the file automatically selected.
IMPROVED: Navigation: modifed highlighting styles to show when a non-audio item is selected for navigation vs. when it is loaded in preview pane but not selected (e.g. click a directory and then click an audio file; the directory item will be dimmed).
IMPROVED: Audio: Greatly simplified shuffle play code and fixed several bugs; shuffle list now correctly updates when individual audio tracks are checked or unchecked.
CHANGED: Moved scale buttons and prev/next image buttons to preview title bar.
CHANGED: Sort by "Name" always sorts files and directories together; "Default" sort always keeps files and directories separate.
FIXED: Text editing: Some issues with split-pane resizing.
FIXED: Cmd/Ctr+W (close) should work now: previewed content will be closed first, then audio, then the browser tab itself.
FIXED: Don't autoload audio cover art when next audio track begins; i.e., leave open whatever file is being previewed, including cover art or lyrics.
FIXED: An issue with sorting by size.
FIXED: An issue with the user UI font setting.
FIXED: Navigation by typed string now correctly scrolls directory list.
OTHER: Many small style fixes and tweaks. Among others, make the previewed image and image grid background color light in default theme.
INTERNAL: Complete code overhaul.

  • Completely rewrote the code that preps the served directory index for processing by the script.
  • Completely rewrote and simplied the sorting code.
  • Alphabetized User Settings for easier editing.
  • Fixes for additional server index configurations.
    – Performance improvments (e.g., removed multiple calls to various functions, reduced initial DOM manipulation, etc.).
  • General code cleanup (e.g., removed unused variables and unnecessary globals, named many formerly anonymous functions, fixed numerous syntax errors, etc.).

Rating: 3

3 Votes