repository·main·Indexed 42 days ago
https://github.com/unhappychoice/mdtsA zero-config CLI tool and Node.js module for previewing local Markdown files in a tree-based web interface with live reloading. Version 0.20.6 features a File Tree API, Outline API, and Configuration API for managing visual settings like themes and fonts. Supports glob pattern filtering via the --glob flag and can be run without installation using npx.
mdts provides several key capabilities for managing markdown-based documentation:
The mdts web interface is organized into three primary panels to facilitate efficient Markdown browsing and reading:
A Header Bar at the top provides access to the Settings dialog, the project GitHub repository, and version information.
Frontmatter is a block of metadata (typically YAML or JSON) placed at the very top of a Markdown file. It is enclosed by triple-dashed lines (---) and is used to store structured information about the document that can be used by processors, static site generators, or documentation tools.
To implement frontmatter, place the YAML block at the start of your file before any other content.
---
title: My Awesome Document
author: Gemini CLI
date: 2025-07-18
tags:
- markdown
- frontmatter
- example
category: Documentation
published: true
version: 1.0.0
---
This document demonstrates the use of **Frontmatter**.mdts uses two distinct storage mechanisms depending on the type of setting:
Browser Settings (localStorage): These are specific to each browser and domain. They control UI-specific preferences such as:
System Configuration File: A JSON file shared across all browser sessions, located at ~/.config/mdts/config.json. This stores core application settings like fonts and themes.
When running mdts, keep the following security aspects in mind:
npx mdts without flags is the most secure method as it limits access to your local machine.--host 0.0.0.0 makes the server accessible over your network. Use this with caution.Settings are managed through two layers:
Stored in your browser to manage session-specific UI preferences:
Global preferences are saved to ~/.config/mdts/config.json on your system:
Settings in mdts are stored in two distinct locations to balance browser flexibility with system-wide consistency:
localStorage): Stores UI-specific preferences such as theme preferences, layout settings, and the current state of the file tree.~/.config/mdts/config.json to maintain consistency across different browser sessions.The mdts server provides a WebSocket interface for real-time file watching and live reloading.
Connection URL: ws://localhost:8521
To start watching a specific file for changes, send a watch-file message via the WebSocket:
{
"type": "watch-file",
"path": "relative/path/to/file.md"
}When a watched file changes, the server will emit a reload message to the client:
{
"type": "reload",
"path": "path/to/changed/file.md"
}Beyond standard CommonMark, mdts supports several GFM extensions:
https://example.com automatically become clickable.~~text~~ to render > [!NOTE]> [!WARNING]> [!NOTE]
> This is a note.
> [!WARNING]
> This is a warning.The mdts viewer supports several interactive modes to change how you interact with Markdown content:
In large projects or monorepos, you can use the --glob (or -g) option to narrow the file tree to a specific subset of Markdown files. This improves startup performance and keeps the UI uncluttered by only showing files that match your pattern.
To use multiple patterns, provide them as separate arguments following the --glob flag.
# Show only package READMEs in a monorepo
npx mdts . -g 'packages/*/README.md'
# Focus on API docs and changelogs
npx mdts . -g 'docs/api/**/*.md' 'CHANGELOG.md'For large projects, follow these best practices to ensure smooth performance:
.gitignore patterns to exclude unnecessary files from being indexed.