vscode-front-matter/lite/QUICKSTART.md

Quick Start Guide for Maintainers

This guide helps you quickly test and publish Front Matter Lite.

Prerequisites

• Node.js 18+
• VS Code installed
• (Optional) vsce installed globally: npm install -g @vscode/vsce

Build and Test (5 minutes)

1. Build the Extension

cd lite
npm install
npm run build

Expected output: dist/extension-web.js created successfully (~12KB)

2. Test in VS Code Extension Development Host

# From the lite directory, press F5 in VS Code
# OR run:
code --extensionDevelopmentPath=/path/to/lite

This opens a new VS Code window with the extension loaded.

3. Test Virtual Workspace Features

In the Extension Development Host:

1. Open Command Palette (F1)
2. Run: "Open Remote Repository"
3. Enter: Any GitHub repo URL (e.g., https://github.com/microsoft/vscode)
4. Verify:
   • "Front Matter Lite" appears in Activity Bar
   • Dashboard loads
   • Information message about virtual workspace mode appears

4. Test Core Features

Register a Folder:

1. In Explorer, right-click any folder
2. Select "Front Matter Lite > Register Content Folder (Lite)"
3. Enter a title
4. Check dashboard shows the folder

Create Content:

1. Click "Create Content" in dashboard
2. Select folder
3. Enter file name
4. Verify file is created with front matter

Package for Distribution

Create VSIX File

cd lite
vsce package

Output: vscode-front-matter-lite-10.9.0.vsix

Test VSIX in github.dev

1. Navigate to any GitHub repo
2. Press . to open github.dev
3. Install extension:
   • Extensions → "..." menu → "Install from VSIX..."
   • Select the generated .vsix file
4. Test features

Publish to Marketplace

Prerequisites

• Azure DevOps account
• Personal Access Token (PAT) with Marketplace publish permissions
• Publisher ID set up

Publish

# First time setup
vsce login <publisher-name>

# Publish
cd lite
vsce publish

Update Version

# In package.json, update version
# Then publish with:
vsce publish minor  # or major, patch

Development Workflow

Watch Mode

npm run dev

Keep this running while developing. Press F5 to test changes.

Make Changes

1. Edit source files in src/
2. Save (watch mode rebuilds automatically)
3. Reload Extension Development Host (Ctrl+R in dev window)
4. Test changes

Debug

1. Set breakpoints in source files
2. Press F5
3. Trigger the feature in dev host
4. Debugger stops at breakpoints

Common Tasks

Update Front Matter Template

Edit in src/extension.ts (~line 170):

const content = `---
title: ${fileName}
description: 
date: ${date}
tags: []
draft: false  // Add new field
---`;

Change Dashboard UI

Edit src/DashboardProvider.ts _getHtmlForWebview() method.

Add New Command

1. Register in package.json contributes.commands
2. Implement in src/extension.ts
3. Add to menu if needed

Modify Configuration Schema

Update package.json contributes.configuration.properties

Troubleshooting

Build Fails

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build

Extension Not Loading

Check:

1. dist/extension-web.js exists
2. package.json has correct browser entry point
3. Output channel for errors

Virtual Workspace Not Detected

Ensure workspace scheme is not 'file':

• github.dev uses 'vscode-vfs'
• Check Output channel for detection message

Quality Checks

Before publishing:

# Build
npm run build

# Check size (should be ~12KB)
ls -lh dist/extension-web.js

# Lint (if you add linting)
npm run lint

# Package
vsce package

Integration with Main Extension

The lite version is independent but uses compatible configuration:

{
  "frontMatter.content.pageFolders": [
    { "title": "Blog", "path": "content/blog" }
  ]
}

This works in both full and lite versions.

Support

For issues:

1. Check Output channel "Front Matter Lite"
2. Check browser console (F12 in github.dev)
3. Review error messages
4. Check GitHub issues

Next Steps

After testing:

1. ✅ Verify features work
2. ✅ Test in github.dev
3. ✅ Get user feedback
4. 📋 Iterate on improvements
5. 🚀 Publish to marketplace
6. 📢 Announce to users

Quick Commands Reference

# Install dependencies
npm install

# Build for production
npm run build

# Build for development (watch mode)
npm run dev

# Package extension
vsce package

# Publish extension
vsce publish

# Test in VS Code
code --extensionDevelopmentPath=$(pwd)

Files to Review

• package.json - Extension manifest
• src/extension.ts - Main logic
• src/DashboardProvider.ts - UI
• README.md - User documentation

That's it! You're ready to test and publish Front Matter Lite. 🚀