Markdown GUI

Markdown GUI (gui-md) is a VS Code extension that transforms .gui.md GitHub Flavored Markdown files into interactive, hierarchical navigation interfaces. Instead of viewing a flat gfm document, you get a three-pane GUI editor: top-level categories as tabs, subcategories as a sidebar, and detailed content cards in the main area—all while keeping the markdown source perfectly editable. Perfect for managing bookmarks, project catalogs, resource libraries, or any structured list of links and information you want to both navigate and use quickly and maintain without leaving VS Code.

This project was born out of preparing to switch away from the Arc browser once The Browser Company announced they were ceasing development. The design was inspired by VS Code's Settings UI with its tabbed navigation, sidebar for organization, and content pane—a pattern that works well for managing structured information. The goal is to bring a similar visual, hierarchical experience to markdown-based organization in VS Code.

Usage

Navigation

• Tabs: Home tab (H1) and category tabs (H2) appear at the top
• Sidebar: Click a tab to see its H3+ sub-categories in the left sidebar
• Main Area: Click a sub-category to view its content on the right

Opening a GUI Markdown File

1. Open any markdown file (.md, .gui.md, etc.) in VS Code
2. Run one of these commands from the command palette:
   • "Edit this gui.md file" - Opens a .gui.md file for editing in the markdown source view
   • "Open in Markdown GUI" - Opens the current file in the Markdown GUI view

Markdown Format

Structure your .gui.md files with the following hierarchy:

• H1 (#): Home - the main title (appears as a single home tab)
• H2 (##): Categories (appear as tabs in the GUI)
• H3+ (###): Sub-categories and content (appear in the sidebar and main area)

# Home

Overview content for the home tab

## Category 1
Main content for category 1

### Sub-category 1.1
Details, links, and information

### Sub-category 1.2
More details and resources

## Category 2
Main content for category 2

### Sub-category 2.1
Items and details

Development

Prerequisites

• Bun (runtime and package manager)
• VS Code
• Node.js 18+ (for VS Code test runner)

Setup

Install dependencies:

bun install

Development Workflow

Build the extension:

bun run build    # One-time build
bun run dev      # Watch mode for development

Run tests:

bun test              # Run all tests
bun test --watch      # Watch mode
bun test --coverage   # With coverage report

Debug the extension:

1. Open the project in VS Code
2. Press F5 to launch the extension in a debug window
3. The debug window will have your extension loaded and active
4. Set breakpoints in src/extension.ts to debug

Project Structure

src/
  └── extension.ts       # Main extension entry point
test/
  ├── unit/             # Unit tests
  ├── integration/      # Integration tests
  └── runTest.ts        # VS Code test runner
out/                    # Compiled output (generated)
package.json            # Dependencies and scripts
tsconfig.json           # TypeScript configuration
bunfig.toml             # Bun configuration

Key Scripts

Command	Purpose
bun run build	Build extension for production
bun run dev	Build with file watch mode
bun test	Run all tests
bun test --watch	Run tests in watch mode

Publishing

Prerequisites

• A Visual Studio Marketplace account
• A Personal Access Token (PAT) from your Azure DevOps organization with Marketplace scope
• vsce CLI tool installed: npm install -g vsce

Steps to Publish

1. Update version in package.json:

   npm version patch  # or minor/major

2. Build for production:

   bun run vscode:prepublish

3. Create the package:

   vsce package

   This generates a .vsix file in the current directory.

4. Publish to VS Code Marketplace:

   vsce publish -p <YOUR_PERSONAL_ACCESS_TOKEN>

   Or if you've already packaged the .vsix file:

   vsce publish -p <YOUR_PERSONAL_ACCESS_TOKEN> --packagePath ./gui-md-0.0.1.vsix

Contributors

• jonmagic - Creator and maintainer