Documentation

VS Code Extension

The PTKRDME VS Code extension provides README management directly in your editor sidebar. Configure sections, auto-detect project metadata, and generate READMEs without leaving VS Code.

Installation

From the VS Code Marketplace

Search for "PTKRDME" in the extensions view or visit the marketplace link.

From source

git clone https://gitlab.com/plantek/ptkrdme/vscode.git
cd vscode-ptkrdme
npm install
npm run build
npm run compile-web

Open the project in VS Code and press F5 to launch the Extension Development Host. The extension activates on startup via onStartupFinished.

Usage

1. Open the PTKRDME sidebar
Click the PTKRDME icon in the activity bar (left sidebar). This opens the webview panel showing all available sections.
2. Review auto-detected sections
When the extension loads, it scans your workspace and runs auto-detection. Relevant shields, brands, and related projects from your dependencies are pre-selected. Sections appear as draggable cards.
3. Configure sections
Click the gear icon on any section to open its configuration modal. Built-in sections have typed fields (selects, multi-selects, inputs). Custom sections store raw markdown in .dev/sections/<name>.md— you can edit them directly in the editor.
4. Reorder and toggle
Drag section cards to reorder. The order is saved automatically to.dev/rdme.config.json.
5. Generate README
Click the floating action button (FAB) at the bottom of the sidebar, or run the "README: Generate" command from the command palette. The README.md is written directly to your workspace root.

Features

Sidebar Panel (Webview SPA)

The sidebar is a React SPA built with Parcel. It communicates with the extension host via postMessage. The message protocol includesconfig (send full state to webview), saveconfig (webview sends edited config back), markdown (trigger and receive rendered markdown), and custom section CRUD operations.

Custom Sections

Create new sections from the sidebar — they store their content as.md files in .dev/sections/. The "open" action opens the file in the editor for direct editing. Custom sections can be renamed or deleted from the sidebar UI.

Config Sync

Configuration is stored in .dev/rdme.config.json at the workspace root. This file can be committed to version control and shared across your team to enforce consistent README structure. The extension saves automatically when sections are configured.

The extension has two runtime halves communicating via postMessage.

Loading diagram...

Architecture

The extension has two runtime halves:

Extension Host (`src/`)

Runs in VS Code's Node.js process. Contains ConfigManager (singleton orchestrator), MarkdownManager (renders sections, writes README.md),AutoDetector (project scanner using vscode.workspace.fs), and section renderers (BrandsSection, ShieldsSection, etc.). TheSidebarProvider creates and manages the webview, routing messages between the UI and ConfigManager.

Webview Frontend (`web/src/`)

A React SPA built with Parcel. Renders section cards in a swapy drag-and-drop grid. The ConfigProvider context manages state and handles the message bridge to the extension host. Section config modals render each field by type (select, multi-select, shields, repeater, etc.).

Message Protocol

Extension host → Webview

{ type: "config",               value: ReactConfigData }  // Full state
{ type: "markdown",             value: string }           // Generated README
{ type: "custom-section-*",     value: { ... } }         // CRUD responses

Webview → Extension host

{ type: "ready" }                                      // On webview load
{ type: "saveconfig",  value: ConfigFile }             // User edited config
{ type: "markdown" }                                   // Trigger generation
{ type: "refresh" }                                    // Re-scan + re-send
{ type: "create-custom-section",  value: title }       // New custom section
{ type: "rename-custom-section",  value: { key, newTitle } }
{ type: "delete-custom-section",  value: key }
{ type: "open-custom-section",    value: key }         // Open .md in editor
{ type: "save-sections-order",    value: names[] }     // After drag-reorder
{ type: "onError",               value: string }

Under the Hood

The extension has its own local copies of ConfigManager,MarkdownManager, and AutoDetector — they are notimported from ptkrdmelib. Instead, the local versions usevscode.workspace.fs via the VSCodeFSHandler wrapper. Only the section autodetect classes (BrandsSectionAutodetect,ShieldsSectionAutodetect) are imported from the library, along with section data objects and types for the webview.

See developer guide → for how to add custom sections.

View on GitLab →