Add dashboard webview, documentation, and testing guides

Co-authored-by: estruyf <2900833+estruyf@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-07 15:11:48 +00:00
parent b61d115566
commit 412673a600
7 changed files with 2610 additions and 3 deletions
+65
View File
@@ -0,0 +1,65 @@
# Changelog - Front Matter Lite
All notable changes to the Front Matter Lite extension will be documented in this file.
## [Unreleased]
### Added
- Initial release of Front Matter Lite for virtual workspaces
- Dashboard webview with folder and file listing
- Register content folders via context menu
- Create content command
- Basic front matter template
- Virtual workspace detection
- Support for github.dev and vscode.dev
- File operations using VS Code FileSystem API
- Configuration persistence
- Content file browser in dashboard
### Features
- ✅ Register content folders
- ✅ Create new markdown files with front matter
- ✅ View registered folders
- ✅ List content files
- ✅ Open files from dashboard
- ✅ Manual refresh
### Limitations
- Dashboard is read-only (no inline editing)
- Limited to 100 files per folder
- No file system watch (manual refresh required)
- No media management
- No git integration
- No custom scripts
- No local server preview
## Architecture
Built as a web extension with:
- Target: `webworker` for browser compatibility
- No Node.js dependencies (fs, path, child_process)
- Uses VS Code FileSystem API (`vscode.workspace.fs`)
- Uses `vscode.Uri` for path operations
- Webview-based dashboard UI
## Roadmap
Future enhancements planned:
- [ ] Inline front matter editing in dashboard
- [ ] Better content filtering and search
- [ ] Tags and categories management
- [ ] Simple content preview
- [ ] Export content list
- [ ] Keyboard shortcuts
- [ ] Better error handling
- [ ] Content statistics
## Version 1.0.0 Goals
Before releasing v1.0.0:
- [ ] Complete testing in github.dev
- [ ] Complete testing in vscode.dev
- [ ] User feedback incorporated
- [ ] Documentation complete
- [ ] Bug fixes for all critical issues
- [ ] Performance optimization
+322
View File
@@ -0,0 +1,322 @@
# Front Matter Lite Setup Guide
This guide will help you set up and start using Front Matter Lite in virtual workspaces.
## Quick Start
### For Users (github.dev / vscode.dev)
1. **Open a repository in github.dev:**
- Navigate to any GitHub repository
- Press `.` (period key)
- OR change `github.com` to `github.dev` in URL
2. **Install Front Matter Lite:**
- Currently in development, will be available on the VS Code Marketplace
- For now, request the `.vsix` file from the project maintainers
3. **Get Started:**
- Look for "Front Matter Lite" in the Activity Bar (left sidebar)
- Click to open the dashboard
### For Developers
1. **Clone and Setup:**
```bash
git clone https://github.com/estruyf/vscode-front-matter.git
cd vscode-front-matter/lite
npm install
```
2. **Build:**
```bash
npm run build
```
3. **Test:**
- Press F5 in VS Code to open Extension Development Host
- OR package and install manually in github.dev
## First Time Setup
### 1. Register Your First Content Folder
After installing, you'll need to tell Front Matter Lite where your content is:
**Method A: Using Explorer Context Menu**
1. Open the Explorer view
2. Right-click on a folder containing your markdown files
3. Select **Front Matter Lite > Register Content Folder (Lite)**
4. Enter a descriptive title (e.g., "Blog Posts")
5. Click OK
**Method B: Manual Configuration**
1. Open Settings (Ctrl/Cmd + ,)
2. Search for "frontMatter.content.pageFolders"
3. Click "Edit in settings.json"
4. Add your folders:
```json
{
"frontMatter.content.pageFolders": [
{
"title": "Blog Posts",
"path": "content/blog"
},
{
"title": "Documentation",
"path": "docs"
}
]
}
```
### 2. Verify Setup
1. Open the Front Matter Lite dashboard
2. You should see your registered folders
3. Click "Refresh" to load existing content files
## Usage
### Creating New Content
1. **Via Dashboard:**
- Open Front Matter Lite dashboard
- Click "Create Content" button
- Select a content folder
- Enter a file name (without .md extension)
- File is created and opened
2. **Via Command Palette:**
- Press F1 or Ctrl/Cmd+Shift+P
- Type "Front Matter Lite: Create Content"
- Follow the prompts
### Viewing Content
1. Open the Front Matter Lite dashboard
2. Registered folders are listed at the top
3. Recent content files are shown below
4. Click any file to open it
### Editing Front Matter
Currently, front matter editing is done directly in the markdown file:
```markdown
---
title: My Post
description: A description of my post
date: 2024-01-07T10:00:00.000Z
tags: [blog, tutorial]
---
# My Post Content
Your content here...
```
## Configuration
### Basic Settings
Add to your workspace `.vscode/settings.json`:
```json
{
"frontMatter.content.pageFolders": [
{
"title": "Blog",
"path": "content/blog"
}
],
"frontMatter.taxonomy.contentTypes": [
{
"name": "default",
"fields": [
{
"title": "Title",
"name": "title",
"type": "string"
},
{
"title": "Description",
"name": "description",
"type": "string"
},
{
"title": "Date",
"name": "date",
"type": "datetime"
},
{
"title": "Tags",
"name": "tags",
"type": "tags"
}
]
}
]
}
```
### Advanced Configuration
For more control over your content:
```json
{
"frontMatter.content.pageFolders": [
{
"title": "Blog Posts",
"path": "content/blog",
"excludeSubdir": false
},
{
"title": "Documentation",
"path": "docs",
"excludeSubdir": true
}
]
}
```
## Workflow Integration
### Hugo Example
```
my-hugo-site/
├── content/
│ ├── blog/ <- Register this folder
│ └── docs/ <- And this one
├── static/
└── config.toml
```
### Jekyll Example
```
my-jekyll-site/
├── _posts/ <- Register this folder
├── _pages/
└── _config.yml
```
### Next.js Example
```
my-nextjs-site/
├── content/ <- Register this folder
│ └── blog/
├── pages/
└── package.json
```
## Troubleshooting
### Extension Not Showing Up
1. **Check Extension is Installed:**
- Open Extensions view (Ctrl/Cmd+Shift+X)
- Search for "Front Matter Lite"
- Verify it's installed and enabled
2. **Check Output Channel:**
- View > Output
- Select "Front Matter Lite" from dropdown
- Look for activation message
### No Folders Showing in Dashboard
1. **Verify folders are registered:**
- Check settings: `frontMatter.content.pageFolders`
- Ensure paths are relative to workspace root
- Click "Refresh" button in dashboard
2. **Check workspace:**
- Ensure you have a workspace/folder open
- Verify the workspace contains the specified paths
### Can't Create Content
1. **Verify folder is registered:**
- At least one folder must be in `frontMatter.content.pageFolders`
2. **Check permissions:**
- Ensure you have write access to the repository
- In github.dev, you need to fork or have write access
### Files Not Appearing
1. **Click "Refresh":**
- Dashboard doesn't auto-update
- Click the "Refresh" button
2. **Check file extensions:**
- Only .md, .mdx, and .markdown files are shown
- Check your files have the correct extension
## Best Practices
### 1. Organize Content by Type
```json
{
"frontMatter.content.pageFolders": [
{ "title": "Blog Posts", "path": "content/blog" },
{ "title": "Tutorials", "path": "content/tutorials" },
{ "title": "Documentation", "path": "docs" }
]
}
```
### 2. Use Consistent Front Matter
Define a template for all your content:
```markdown
---
title: Post Title
description: Brief description
date: 2024-01-07T10:00:00.000Z
tags: []
categories: []
draft: false
---
```
### 3. Commit Configuration
Add `.vscode/settings.json` to your repository so all team members have the same setup.
### 4. Regular Backups
Even though you're in a virtual workspace:
- Commit changes regularly
- Push to GitHub frequently
- Use branches for experiments
## Getting Help
- **Documentation:** [https://frontmatter.codes](https://frontmatter.codes)
- **Issues:** [GitHub Issues](https://github.com/estruyf/vscode-front-matter/issues)
- **Discussions:** [GitHub Discussions](https://github.com/estruyf/vscode-front-matter/discussions)
## Next Steps
1. **Explore the Dashboard:**
- Familiarize yourself with the interface
- Try creating a few test posts
2. **Customize Front Matter:**
- Define content types that match your needs
- Add custom fields
3. **Share with Team:**
- Commit your configuration
- Share the setup guide with collaborators
4. **Upgrade to Full Version:**
- For advanced features, install the full Front Matter extension in VS Code Desktop
- Enjoy media management, custom scripts, and more
+202
View File
@@ -0,0 +1,202 @@
# Testing Front Matter Lite
This guide explains how to test the Front Matter Lite extension in various environments.
## Prerequisites
- Built extension (run `npm run build`)
- VS Code installed locally OR
- Access to github.dev/vscode.dev
## Testing Methods
### 1. Testing in VS Code Extension Development Host
This is the fastest way to test during development:
1. Open the lite folder in VS Code
2. Build the extension: `npm run build`
3. Press F5 to launch Extension Development Host
4. In the new window, open a folder or workspace
5. The Front Matter Lite sidebar should appear in the Activity Bar
**To test virtual workspace features:**
1. In Extension Development Host, open Command Palette (F1)
2. Run "Open Remote Repository"
3. Enter a GitHub repository URL (e.g., `https://github.com/username/repo`)
4. The extension will activate in virtual workspace mode
### 2. Testing in github.dev
1. Package the extension:
```bash
npm install -g @vscode/vsce
vsce package
```
2. This creates a `.vsix` file
3. Navigate to github.dev:
- Go to any GitHub repository
- Press `.` (period key)
- OR change `github.com` to `github.dev` in the URL
4. Install the extension:
- Click Extensions icon in Activity Bar
- Click "..." menu
- Choose "Install from VSIX..."
- Select the generated `.vsix` file
5. Test the features
### 3. Testing in vscode.dev
Similar to github.dev:
1. Go to https://vscode.dev
2. Open a folder or repository
3. Install the extension from VSIX (as above)
## Test Scenarios
### Scenario 1: Register a Content Folder
1. Open a repository with markdown files
2. In Explorer, right-click on a folder
3. Select "Front Matter Lite > Register Content Folder (Lite)"
4. Enter a title
5. Verify:
- Success message appears
- Folder appears in Dashboard
- Configuration is saved
### Scenario 2: Create Content
1. Ensure at least one folder is registered
2. Click "Create Content" in the Dashboard OR
3. Run Command: "Front Matter Lite: Create Content (Lite)"
4. Select a content folder
5. Enter a file name
6. Verify:
- File is created with front matter
- File opens in editor
- Front matter includes title, date, tags
### Scenario 3: View Content in Dashboard
1. Register a folder with existing markdown files
2. Click "Refresh" in the Dashboard
3. Verify:
- Files are listed
- File names and folders are shown
- Clicking a file opens it
### Scenario 4: Virtual Workspace Detection
1. Open repository via "Open Remote Repository" or github.dev
2. Check Output channel "Front Matter Lite"
3. Verify message: "Running in virtual workspace mode"
4. Verify information message appears about limited features
## Expected Behavior
### Working Features ✅
- ✅ Register content folders
- ✅ Create new content files
- ✅ View registered folders in dashboard
- ✅ List content files in dashboard
- ✅ Open files from dashboard
- ✅ Basic front matter template
- ✅ Virtual workspace detection
### Known Limitations ❌
- ❌ Cannot edit front matter in UI (use editor)
- ❌ No media upload/management
- ❌ No git integration
- ❌ No custom scripts
- ❌ No file system watch (manual refresh needed)
- ❌ Limited to 100 files per folder
## Debugging
### Enable Logging
1. View > Output
2. Select "Front Matter Lite" from dropdown
3. Check for error messages
### Common Issues
**Extension not appearing:**
- Check that it's built: `npm run build`
- Verify `dist/extension-web.js` exists
- Check package.json has correct `browser` entry point
**Commands not working:**
- Check Output channel for errors
- Verify workspace has folders
- Ensure running in compatible environment
**Dashboard not loading:**
- Check browser console (if in github.dev/vscode.dev)
- Verify webview is enabled
- Check for Content Security Policy errors
### Browser Console (github.dev/vscode.dev)
1. Press F12 to open Developer Tools
2. Check Console tab for JavaScript errors
3. Check Network tab for failed requests
## Manual Testing Checklist
- [ ] Extension activates in virtual workspace
- [ ] Dashboard appears in Activity Bar
- [ ] Can register a folder via context menu
- [ ] Registered folders appear in dashboard
- [ ] Can create content via command
- [ ] Content file has correct front matter
- [ ] Files appear in dashboard after refresh
- [ ] Clicking file in dashboard opens it
- [ ] Virtual workspace mode detected
- [ ] Configuration persists
- [ ] Works in github.dev
- [ ] Works in vscode.dev
- [ ] Works in local VS Code
## Performance Testing
Test with different repository sizes:
1. Small repo (<10 files)
2. Medium repo (10-50 files)
3. Large repo (50-100 files)
Verify:
- Dashboard loads within 2 seconds
- File creation is responsive
- No UI freezing
## Reporting Issues
When reporting issues, include:
1. Environment (github.dev, vscode.dev, local)
2. Workspace type (virtual or file)
3. Steps to reproduce
4. Output channel logs
5. Browser console errors (if applicable)
6. Extension version
## Next Steps
After testing:
1. Document any issues found
2. Verify all test scenarios pass
3. Test in different browsers (Chrome, Firefox, Edge, Safari)
4. Get feedback from users
5. Iterate on improvements
+1724
View File
File diff suppressed because it is too large Load Diff
+18
View File
@@ -40,6 +40,24 @@
"workspaceContains:**/frontmatter.json"
],
"contributes": {
"viewsContainers": {
"activitybar": [
{
"id": "frontmatter-lite",
"title": "Front Matter Lite",
"icon": "$(file-text)"
}
]
},
"views": {
"frontmatter-lite": [
{
"type": "webview",
"id": "frontMatterLite.dashboard",
"name": "Dashboard"
}
]
},
"commands": [
{
"command": "frontMatter.lite.dashboard",
+267
View File
@@ -0,0 +1,267 @@
import * as vscode from 'vscode';
export class DashboardProvider implements vscode.WebviewViewProvider {
public static readonly viewType = 'frontMatterLite.dashboard';
private _view?: vscode.WebviewView;
constructor(private readonly _extensionUri: vscode.Uri) {}
public resolveWebviewView(
webviewView: vscode.WebviewView,
context: vscode.WebviewViewResolveContext,
_token: vscode.CancellationToken
) {
this._view = webviewView;
webviewView.webview.options = {
enableScripts: true,
localResourceRoots: [this._extensionUri]
};
webviewView.webview.html = this._getHtmlForWebview(webviewView.webview);
// Handle messages from the webview
webviewView.webview.onDidReceiveMessage(async (data) => {
switch (data.type) {
case 'createContent': {
await vscode.commands.executeCommand('frontMatter.lite.createContent');
break;
}
case 'registerFolder': {
vscode.window.showInformationMessage(
'Please right-click on a folder in the Explorer and select "Front Matter Lite > Register Content Folder"'
);
break;
}
case 'refreshContent': {
await this._refreshContent();
break;
}
case 'openFile': {
const uri = vscode.Uri.parse(data.uri);
const doc = await vscode.workspace.openTextDocument(uri);
await vscode.window.showTextDocument(doc);
break;
}
}
});
// Initial load
this._refreshContent();
}
private async _refreshContent() {
if (!this._view) {
return;
}
const config = vscode.workspace.getConfiguration('frontMatter');
const pageFolders = config.get<Array<{ title: string; path: string }>>('content.pageFolders') || [];
const contentFiles: Array<{ uri: string; name: string; folder: string }> = [];
// Scan all registered folders for markdown files
for (const folder of pageFolders) {
try {
const workspaceFolders = vscode.workspace.workspaceFolders;
if (!workspaceFolders) continue;
const folderUri = vscode.Uri.joinPath(workspaceFolders[0].uri, folder.path);
const pattern = new vscode.RelativePattern(folderUri, '**/*.{md,mdx,markdown}');
const files = await vscode.workspace.findFiles(pattern, '**/node_modules/**', 100);
for (const file of files) {
const relativePath = vscode.workspace.asRelativePath(file);
const fileName = relativePath.split('/').pop() || '';
contentFiles.push({
uri: file.toString(),
name: fileName,
folder: folder.title
});
}
} catch (error) {
console.error(`Error scanning folder ${folder.path}:`, error);
}
}
// Send data to webview
this._view.webview.postMessage({
type: 'updateContent',
folders: pageFolders,
files: contentFiles
});
}
private _getHtmlForWebview(webview: vscode.Webview) {
return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Front Matter Lite</title>
<style>
body {
padding: 10px;
color: var(--vscode-foreground);
font-family: var(--vscode-font-family);
font-size: var(--vscode-font-size);
}
.header {
margin-bottom: 20px;
}
h2 {
font-size: 18px;
margin: 0 0 10px 0;
}
.button-group {
display: flex;
gap: 8px;
margin-bottom: 20px;
}
button {
background: var(--vscode-button-background);
color: var(--vscode-button-foreground);
border: none;
padding: 8px 12px;
cursor: pointer;
border-radius: 2px;
}
button:hover {
background: var(--vscode-button-hoverBackground);
}
.section {
margin-bottom: 20px;
}
.section-title {
font-weight: bold;
margin-bottom: 8px;
font-size: 14px;
}
.folder-list, .file-list {
list-style: none;
padding: 0;
margin: 0;
}
.folder-item, .file-item {
padding: 8px;
margin-bottom: 4px;
background: var(--vscode-list-inactiveSelectionBackground);
border-radius: 2px;
}
.file-item {
cursor: pointer;
}
.file-item:hover {
background: var(--vscode-list-hoverBackground);
}
.file-name {
font-weight: 500;
}
.file-folder {
font-size: 12px;
color: var(--vscode-descriptionForeground);
margin-top: 2px;
}
.empty-state {
text-align: center;
padding: 40px 20px;
color: var(--vscode-descriptionForeground);
}
.empty-state-icon {
font-size: 48px;
margin-bottom: 10px;
}
</style>
</head>
<body>
<div class="header">
<h2>Front Matter Lite</h2>
<div class="button-group">
<button id="createBtn">Create Content</button>
<button id="registerBtn">Register Folder</button>
<button id="refreshBtn">Refresh</button>
</div>
</div>
<div id="content">
<div class="empty-state">
<div class="empty-state-icon">📝</div>
<p>Loading content...</p>
</div>
</div>
<script>
const vscode = acquireVsCodeApi();
document.getElementById('createBtn').addEventListener('click', () => {
vscode.postMessage({ type: 'createContent' });
});
document.getElementById('registerBtn').addEventListener('click', () => {
vscode.postMessage({ type: 'registerFolder' });
});
document.getElementById('refreshBtn').addEventListener('click', () => {
vscode.postMessage({ type: 'refreshContent' });
});
window.addEventListener('message', event => {
const message = event.data;
switch (message.type) {
case 'updateContent': {
updateContent(message.folders, message.files);
break;
}
}
});
function updateContent(folders, files) {
const contentDiv = document.getElementById('content');
if (folders.length === 0) {
contentDiv.innerHTML = \`
<div class="empty-state">
<div class="empty-state-icon">📁</div>
<p>No content folders registered</p>
<p style="font-size: 12px;">Click "Register Folder" to get started</p>
</div>
\`;
return;
}
let html = '<div class="section"><div class="section-title">Content Folders</div><ul class="folder-list">';
folders.forEach(folder => {
html += \`<li class="folder-item">\${folder.title} <span style="color: var(--vscode-descriptionForeground);">(\${folder.path})</span></li>\`;
});
html += '</ul></div>';
if (files.length > 0) {
html += '<div class="section"><div class="section-title">Recent Content</div><ul class="file-list">';
files.forEach(file => {
html += \`
<li class="file-item" data-uri="\${file.uri}">
<div class="file-name">\${file.name}</div>
<div class="file-folder">\${file.folder}</div>
</li>
\`;
});
html += '</ul></div>';
} else {
html += '<div class="empty-state"><p>No content files found</p></div>';
}
contentDiv.innerHTML = html;
// Add click handlers to files
document.querySelectorAll('.file-item').forEach(item => {
item.addEventListener('click', () => {
const uri = item.getAttribute('data-uri');
vscode.postMessage({ type: 'openFile', uri });
});
});
}
</script>
</body>
</html>`;
}
}
+12 -3
View File
@@ -1,4 +1,5 @@
import * as vscode from 'vscode';
import { DashboardProvider } from './DashboardProvider';
/**
* Lite version of Front Matter CMS for virtual workspaces
@@ -12,12 +13,20 @@ export function activate(context: vscode.ExtensionContext) {
outputChannel = vscode.window.createOutputChannel('Front Matter Lite');
outputChannel.appendLine('Front Matter Lite activated for virtual workspace');
// Register Dashboard Webview Provider
const dashboardProvider = new DashboardProvider(context.extensionUri);
context.subscriptions.push(
vscode.window.registerWebviewViewProvider(
DashboardProvider.viewType,
dashboardProvider
)
);
// Register Dashboard command
context.subscriptions.push(
vscode.commands.registerCommand('frontMatter.lite.dashboard', async () => {
vscode.window.showInformationMessage(
'Front Matter Lite Dashboard: This feature is under development for virtual workspaces'
);
// Focus on the dashboard view
vscode.commands.executeCommand('frontMatterLite.dashboard.focus');
})
);