Markdown Navigator

A powerful Raycast extension for managing and navigating your Markdown files with ease.

Features

• Complete File Indexing: Recursively indexes all supported Markdown files in your configured directory
• Pagination: Navigate through large collections of files with easy pagination
• Tag Filtering: Filter files by tags extracted from your Markdown content
• Color-coded Tags: Visually identify important, draft, complete, review, and archive tags
• Folder Organization: Files are automatically grouped by folder for better organization
• File Management: Create, open, delete, and move files to trash directly from Raycast
• Editor Integration: Open files in your preferred Markdown editor, including Typora
• Full Search Coverage: Search always runs across the complete Markdown file index

Installation

1. Install Raycast
2. Open Raycast and search for "Extensions"
3. Click "+" and search for "Markdown Navigator"
4. Install the extension
5. Configure the extension with your Markdown directory in preferences

Configuration

The extension requires a valid Markdown directory to be set in preferences:

1. Open Raycast
2. Search for "Markdown Navigator"
3. Press ⌘ + , to open preferences
4. Set your Markdown directory path

Usage

Basic Navigation

• Search: Type to search for file names or folders
• Browse: Use arrow keys to navigate through the list
• Pagination: Use ⌘ + ← and ⌘ + → to navigate between pages

File Actions

• Open in Default App: Press ⏎
• Open With...: Press ⌘ + ⇧ + O to choose an application
• Show in Finder: Press ⌘ + F
• Copy Path: Press ⌘ + ⇧ + C
• Move to Trash: Press ⌃ + X
• Delete File: Press ⌃ + ⌘ + X

File Creation

• Create New File: Press ⌘ + N to create a new Markdown file
• Specify file name and optional content
• Choose a directory or use the current folder

Template-Based File Creation

• Multiple Templates: Choose from various pre-defined templates when creating files:

  • Basic: Simple structure with title, date, and tags
  • Meeting: Template for meeting notes with agenda and action items
  • Blog: Front matter format suitable for blog posts
  • Project: Project planning template with goals and timeline
  • Empty: Blank file with no pre-defined content

• Context-Aware Creation: Create new files directly in the folder you're currently browsing

  • When viewing files in a specific folder, new files will be created in that location
  • Press ⌘ + N while browsing to create a file in the current context
  • Templates automatically include current date and specified tags

Tag Management

• Smart Tag Extraction: Tags are automatically extracted from:

  • Inline hashtags in Markdown content (#tag)
  • YAML frontmatter tags

  tags: [tag1, tag2]
  

  • Supports both English and Chinese tags

• System Tags vs. Custom Tags: Tags are categorized into:

  • System Tags: Pre-defined tags with color coding for quick visual identification
    • Important (Red)
    • Draft (Yellow)
    • Complete (Green)
    • Review (Orange)
    • Archive (Blue)
  • Custom Tags: User-defined tags for personal organization

• Tag Filtering Options:

  • Dropdown Filter: Use the dropdown in the search bar to filter by system or custom tags
  • Browse Tags: Press ⌘ + T to open a dedicated tag search interface with sections
  • Toggle Color Tags: Press ⌘ + E to show/hide color-coded tags
  • Clear Tag Filter: Press ⌘ + ⇧ + T when a tag is selected to clear the filter

• Tag Visualization:

  • Color-coded icons for system tags
  • Organized sections for system and custom tags in the tag search view
  • Tag counts displayed in the interface

Other Actions

• Refresh List: Press ⌘ + R to refresh the file list
• Open Preferences: Press ⌘ + ⇧ + P to open extension preferences

Performance Considerations

The extension asynchronously indexes all supported Markdown files in your configured directory, then displays them with pagination for easier browsing. If you have a large collection of Markdown files, you can:

1. Use search and tag filtering to narrow down results
2. Navigate through pages to browse indexed files (20 files per page)
3. Press ⌘ + R to refresh the index after adding, renaming, or deleting files outside Raycast

Supported Markdown extensions are .md, .markdown, .mdown, and .mkd. Plain text files such as .txt are not indexed.

The indexer skips hidden folders, node_modules, macOS user Library folders during broad scans, and VS Code history files. Regular note folders named Library are still indexed. If an individual Markdown file disappears or becomes inaccessible during indexing, it is skipped while the remaining files stay available.

Requirements

• Raycast
• macOS
• A Markdown editor

Support

If you encounter any issues or have suggestions for improvements, please submit an issue on the GitHub repository.

License

MIT