Project Docs - VS Code Extension

A VS Code extension for organizing and managing project documentation directly within the editor.

Features

Dedicated Sidebar: Access your project documentation through a custom sidebar view
Markdown Support: Create and edit markdown files with built-in templates
Diagram Support: Create diagrams using Mermaid (text-based) or Draw.io (visual)
Flexible Structure: Organize your documentation with folders and files however you prefer
Git-Friendly: All documentation is versioned with your project
Quick Actions: Create, rename, delete files and folders with context menu commands

Installation

Prerequisites

For diagram support, install the Draw.io Integration extension:

Search for "Draw.io Integration" in VS Code Extensions
Install the extension by hediet

See DIAGRAMS_GUIDE.md for detailed instructions on working with diagrams.

From Source

Clone this repository
Install dependencies:
```
npm install
```
Compile the extension:
```
npm run compile
```
Press F5 in VS Code to launch a new Extension Development Host window

From VS Code Marketplace (Coming Soon)

Search for "Project Docs" in the VS Code Extensions marketplace and click Install.

Usage

Getting Started

Open a project folder in VS Code
Click on the "Project Docs" icon in the activity bar (left sidebar)
Click "Initialize Project Documentation" to create the initial structure

Initial Structure

When you initialize the documentation, the following structure is created:

.project-docs/
├─ docs/
│  ├─ overview.md
│  ├─ architecture.md
│  └─ onboarding.md
├─ notes/
│  └─ useful-links.md
├─ diagrams/
└─ project.json

Note: This structure is just a starting point. You're free to reorganize, rename, delete, or add any folders and files as needed.

Creating Files

Right-click on a folder or anywhere in the tree view
Select "New File"
Enter the filename (e.g., my-document.md)
The file will be created with an appropriate template and opened in the editor

Creating Folders

Right-click on a folder or anywhere in the tree view
Select "New Folder"
Enter the folder name
The folder will be created and appear in the tree

Renaming Items

Right-click on a file or folder
Select "Rename"
Enter the new name
The item will be renamed

Deleting Items

Right-click on a file or folder
Select "Delete"
Confirm the deletion
The item will be removed

Opening Files

Simply click on any file in the tree view to open it in the editor. Supported file types include:

.md - Markdown files
.drawio, .drawio.svg, .drawio.png - Draw.io diagrams (requires Draw.io Integration extension)
.json, .yaml, .yml - Configuration files
.txt - Text files
And more!

Note: For diagram support, install the Draw.io Integration extension. See DIAGRAMS_GUIDE.md for details.

Team Collaboration

The extension supports team collaboration through Git-based workflow:

All documentation lives in the project repository
Team members can edit files and commit changes
Pull requests allow review of documentation changes
Git provides complete history and version control

For real-time collaboration, consider:

VS Code Live Share - Free extension for real-time collaboration sessions
Git + Pull Requests - Standard workflow for continuous collaboration
Specialized Tools - Confluence, GitBook, Notion for advanced features

See COLLABORATION_GUIDE.md for detailed information about collaboration options and future plans.

Revealing in Explorer

Right-click on any file or folder
Select "Reveal in Explorer"
The item will be highlighted in VS Code's file explorer

File Templates

The extension provides built-in templates for common documentation files:

overview.md: Project overview template
architecture.md: Architecture documentation template
onboarding.md: Onboarding guide template
useful-links.md: Useful links collection template
project.json: Project metadata template

Keyboard Shortcuts

Currently, there are no default keyboard shortcuts. You can add your own by editing your VS Code keybindings.json:

{
  "key": "ctrl+shift+d",
  "command": "projectDocs.initialize"
}

Commands

Command	Description
`Project Docs: Initialize Documentation`	Create the initial documentation structure
`Project Docs: Refresh Documentation`	Refresh the documentation tree view
`Project Docs: New File`	Create a new file
`Project Docs: New Folder`	Create a new folder
`Project Docs: Rename`	Rename a file or folder
`Project Docs: Delete`	Delete a file or folder
`Project Docs: Reveal in Explorer`	Reveal item in VS Code explorer
`Project Docs: Open Markdown Preview`	Open markdown preview side-by-side

Development

Project Structure

src/
├─ extension.ts                    # Main extension entry point
├─ providers/
│  └─ ProjectDocsTreeProvider.ts   # Tree data provider for sidebar
├─ models/
│  ├─ ProjectDocsItem.ts           # Tree item model
│  └─ ItemType.ts                  # Item type enum
├─ commands/
│  ├─ initializeProjectDocs.ts     # Initialize command
│  ├─ createFile.ts                # Create file command
│  ├─ createFolder.ts              # Create folder command
│  ├─ renameItem.ts                # Rename command
│  ├─ deleteItem.ts                # Delete command
│  ├─ refreshTree.ts               # Refresh command
│  ├─ openItem.ts                  # Open file command
│  └─ openInExplorer.ts            # Reveal in explorer command
├─ services/
│  ├─ projectDocsService.ts       # Core documentation service
│  ├─ workspaceService.ts          # Workspace operations
│  └─ fileTemplatesService.ts      # File templates
└─ utils/
   ├─ paths.ts                     # Path utilities
   └─ fileIcons.ts                 # File icon utilities

Building

npm run compile

Watching for Changes

npm run watch

Linting

npm run lint

Roadmap

MVP 1 (Current)

✅ Sidebar tree view
✅ Initialize documentation structure
✅ Create files and folders
✅ Rename and delete items
✅ Open files in editor
✅ File templates
✅ File system watcher

MVP 2 (Planned)

Markdown preview
Search functionality
Favorites and recent files
Better icons
Quick file creation from templates
ADR (Architecture Decision Record) support
Configurable documentation folder

MVP 3 (Planned)

Git integration
Automatic change detection
Advanced templates
Project metadata support
Enhanced navigation
File type filtering
Full-text search

Future (Advanced)

Real-time collaboration
Backend synchronization
User presence
Shared comments
AI assistant integration
Auto-generated documentation
Code-doc consistency analysis

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Project Docs

company-docs