diff --git a/lite/QUICKSTART.md b/lite/QUICKSTART.md new file mode 100644 index 00000000..37088143 --- /dev/null +++ b/lite/QUICKSTART.md @@ -0,0 +1,263 @@ +# 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 + +```bash +cd lite +npm install +npm run build +``` + +Expected output: `dist/extension-web.js` created successfully (~12KB) + +### 2. Test in VS Code Extension Development Host + +```bash +# 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 + +```bash +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 + +```bash +# First time setup +vsce login + +# Publish +cd lite +vsce publish +``` + +### Update Version + +```bash +# In package.json, update version +# Then publish with: +vsce publish minor # or major, patch +``` + +## Development Workflow + +### Watch Mode + +```bash +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): + +```typescript +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 + +```bash +# 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: + +```bash +# 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: + +```json +{ + "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 + +```bash +# 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. 🚀