Skip to content

Commit 6aaa852

Browse files
alpha912alpha912
committed
docs: add comprehensive documentation
- Create /docs directory with README.md - Add installation guide - Add usage instructions - Include configuration details - Provide API reference - Include contributing guidelines - Add changelog - Create troubleshooting guide This commit significantly improves project documentation, making it easier for users to understand, use, and contribute to CodebaseMD.
1 parent 0104090 commit 6aaa852

File tree

8 files changed

+404
-0
lines changed

8 files changed

+404
-0
lines changed

‎docs/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# CodebaseMD Documentation
2+
3+
Welcome to the documentation for CodebaseMD, a Visual Studio Code extension that allows you to export your codebase or selected files as a Markdown file.
4+
5+
## Table of Contents
6+
7+
1. [Installation](./installation.md)
8+
2. [Usage](./usage.md)
9+
3. [Configuration](./configuration.md)
10+
4. [API Reference](./api-reference.md)
11+
5. [Contributing](./contributing.md)
12+
6. [Changelog](./changelog.md)
13+
7. [Troubleshooting](./troubleshooting.md)
14+
15+
For the main project README, please refer to the [README.md](../README.md) in the root directory.

‎docs/api-reference.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# API Reference
2+
3+
CodebaseMD is a Visual Studio Code extension and does not expose a public API for other extensions to consume. However, this document provides an overview of the main functions and their purposes within the extension.
4+
5+
## Core Functions
6+
7+
### `activate(context: vscode.ExtensionContext)`
8+
9+
This function is called when the extension is activated. It registers the commands that the extension provides.
10+
11+
### `exportCodebase()`
12+
13+
Exports the entire codebase of the currently open workspace.
14+
15+
### `exportSelectedFiles(uris: vscode.Uri[])`
16+
17+
Exports only the selected files and folders.
18+
19+
### `getAllFiles(dir: string): Promise<string[]>`
20+
21+
Recursively gets all files in a directory, respecting ignore patterns.
22+
23+
### `getFilesFromUris(uris: vscode.Uri[]): Promise<string[]>`
24+
25+
Gets all files from the provided URIs, which may include both files and folders.
26+
27+
### `createIgnoreInstance(rootDir: string): Ignore`
28+
29+
Creates an instance of the `ignore` package, configured with patterns from `.gitignore` and default ignored items.
30+
31+
### `isLargeFile(fileName: string): boolean`
32+
33+
Determines if a file should be considered "large" and excluded from the export.
34+
35+
### `isSupportedFile(fileName: string): boolean`
36+
37+
Checks if a file type is supported for content export.
38+
39+
### `generateMarkdown(files: string[], rootPath: string): Promise<string>`
40+
41+
Generates the Markdown content for the given files.
42+
43+
### `generateFolderStructure(files: string[], rootPath: string): string`
44+
45+
Creates a tree-like representation of the folder structure.
46+
47+
### `saveMarkdownFile(content: string)`
48+
49+
Prompts the user to choose a save location and saves the generated Markdown content.
50+
51+
## Extension Commands
52+
53+
CodebaseMD registers two commands that can be invoked from the Command Palette:
54+
55+
1. `codebaseMD.exportAll`: Exports the entire codebase as Markdown.
56+
2. `codebaseMD.exportSelected`: Exports selected files or folders as Markdown.
57+
58+
## Events
59+
60+
CodebaseMD does not currently emit any custom events.
61+
62+
## Configuration
63+
64+
The extension does not currently use VS Code's configuration API. All configuration is hard-coded in the source files.
65+
66+
## Extending CodebaseMD
67+
68+
While CodebaseMD doesn't provide an API for other extensions, you can fork the project and modify it to suit your needs. Some potential extension points include:
69+
70+
- Adding new file type support
71+
- Implementing custom markdown generation logic
72+
- Adding new commands for different export options
73+
74+
If you develop features that you think would be valuable to the community, consider submitting a pull request to the main repository.
75+
76+
For more information on developing extensions for Visual Studio Code, refer to the [official documentation](https://code.visualstudio.com/api).

‎docs/changelog.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Changelog
2+
3+
All notable changes to the CodebaseMD extension will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2024-09-26
9+
10+
### Added
11+
- Initial release of CodebaseMD
12+
- Feature to export entire codebase as Markdown
13+
- Feature to export selected files and folders as Markdown
14+
- Automatic exclusion of files and folders based on .gitignore and common patterns
15+
- Support for multiple file types
16+
- Folder structure visualization in the generated Markdown
17+
- Project statistics in the generated Markdown
18+
19+
### Changed
20+
- N/A (Initial release)
21+
22+
### Deprecated
23+
- N/A (Initial release)
24+
25+
### Removed
26+
- N/A (Initial release)
27+
28+
### Fixed
29+
- N/A (Initial release)
30+
31+
### Security
32+
- N/A (Initial release)
33+
34+
## [Unreleased]
35+
36+
### Planned Features
37+
- User-configurable ignore patterns
38+
- Option to include or exclude specific file types
39+
- Customizable Markdown output format
40+
- Integration with version control systems for diff exports
41+
- Performance improvements for large codebases
42+
43+
---
44+
45+
Note: As this is the initial release, there are no previous versions to compare against. Future updates will include more detailed changelogs comparing to previous versions.

‎docs/configuration.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Configuration
2+
3+
Currently, CodebaseMD does not have user-configurable settings through the Visual Studio Code settings interface. However, you can customize some behaviors by modifying the source code directly.
4+
5+
## Customizing Ignored Files and Directories
6+
7+
To change which files and directories are ignored during export:
8+
9+
1. Open the `src/extension.ts` file in the project
10+
2. Locate the `createIgnoreInstance` function
11+
3. Modify the `ig.add()` call to add or remove patterns from the ignore list
12+
13+
Example:
14+
15+
```typescript
16+
ig.add([
17+
'node_modules/',
18+
'build/',
19+
'out/',
20+
'dist/',
21+
'.git/',
22+
// Add your custom ignore patterns here
23+
'custom-ignore-folder/',
24+
'*.custom-extension'
25+
]);
26+
```
27+
28+
## Customizing Supported File Types
29+
30+
To change which file types are considered "supported" and have their contents included in the export:
31+
32+
1. Open the `src/extension.ts` file
33+
2. Find the `isSupportedFile` function
34+
3. Modify the `supportedExtensions` array to add or remove file extensions
35+
36+
Example:
37+
38+
```typescript
39+
const supportedExtensions = [
40+
'.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.json', '.md', '.txt',
41+
'.py', '.java', '.c', '.cpp', '.cs', '.rb', '.go', '.php', '.sh', '.xml',
42+
// Add your custom extensions here
43+
'.custom', '.myext'
44+
];
45+
```
46+
47+
## Customizing Large File Exclusions
48+
49+
To change which files are considered "large" and excluded from the export:
50+
51+
1. Open the `src/extension.ts` file
52+
2. Locate the `isLargeFile` function
53+
3. Modify the `largeFiles` array to add or remove file names
54+
55+
Example:
56+
57+
```typescript
58+
function isLargeFile(fileName: string): boolean {
59+
const largeFiles = ['package-lock.json', 'yarn.lock', 'my-large-file.json'];
60+
return largeFiles.includes(fileName);
61+
}
62+
```
63+
64+
**Note**: After making any changes to the source code, you'll need to recompile the extension and reinstall it in Visual Studio Code for the changes to take effect.
65+
66+
## Future Configuration Plans
67+
68+
We plan to add user-configurable settings in future versions of CodebaseMD. This will allow users to customize the extension's behavior without modifying the source code. If you have suggestions for configurable options, please [open an issue](https://github.com/alpha912/codebase-md/issues) on GitHub.

‎docs/contributing.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Contributing to CodebaseMD
2+
3+
We welcome contributions to CodebaseMD! Whether you're fixing bugs, adding new features, improving documentation, or suggesting ideas, we appreciate your involvement. This guide will help you get started with contributing to the project.
4+
5+
## Getting Started
6+
7+
1. Fork the repository on GitHub
8+
2. Clone your fork locally:
9+
```
10+
git clone https://github.com/your-username/codebase-md.git
11+
```
12+
3. Create a new branch for your changes:
13+
```
14+
git checkout -b feature/your-feature-name
15+
```
16+
17+
## Setting Up the Development Environment
18+
19+
1. Ensure you have [Node.js](https://nodejs.org/) installed (version 12.x or later)
20+
2. Install the project dependencies:
21+
```
22+
npm install
23+
```
24+
3. Open the project in Visual Studio Code
25+
26+
## Making Changes
27+
28+
1. Make your changes in the `src` directory
29+
2. If you're adding a new feature, consider adding tests in the `src/test` directory
30+
3. Run the linter to ensure your code follows the project's style guidelines:
31+
```
32+
npm run lint
33+
```
34+
4. Compile the TypeScript code:
35+
```
36+
npm run compile
37+
```
38+
5. Test your changes by running the extension in a new VS Code window:
39+
- Press `F5` in VS Code to launch the extension in debug mode
40+
41+
## Submitting a Pull Request
42+
43+
1. Commit your changes:
44+
```
45+
git add .
46+
git commit -m "Your descriptive commit message"
47+
```
48+
2. Push to your fork:
49+
```
50+
git push origin feature/your-feature-name
51+
```
52+
3. Go to the [CodebaseMD repository](https://github.com/alpha912/codebase-md) and create a new pull request
53+
4. Describe your changes in the pull request description
54+
5. Wait for a maintainer to review your pull request
55+
56+
## Coding Guidelines
57+
58+
- Follow the existing code style and conventions used in the project
59+
- Write clear, concise commit messages
60+
- Keep pull requests focused on a single feature or bug fix
61+
- Add comments to your code where necessary to explain complex logic
62+
63+
## Reporting Issues
64+
65+
If you find a bug or have a suggestion for improvement:
66+
67+
1. Check if the issue already exists in the [GitHub issue tracker](https://github.com/alpha912/codebase-md/issues)
68+
2. If not, create a new issue, providing as much detail as possible:
69+
- Steps to reproduce (for bugs)
70+
- Expected behavior
71+
- Actual behavior
72+
- VS Code version
73+
- CodebaseMD version
74+
- Operating system
75+
76+
## Community Guidelines
77+
78+
- Be respectful and considerate in all interactions
79+
- Provide constructive feedback
80+
- Focus on the issue or idea being discussed, not the individuals involved
81+
- Follow the [Code of Conduct](../CODE_OF_CONDUCT.md)
82+
83+
Thank you for contributing to CodebaseMD!

‎docs/installation.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Installation
2+
3+
There are two ways to install the CodebaseMD extension for Visual Studio Code:
4+
5+
## 1. From Visual Studio Marketplace
6+
7+
1. Open Visual Studio Code
8+
2. Go to the Extensions view by clicking on the square icon in the left sidebar or pressing `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
9+
3. Search for "CodebaseMD"
10+
4. Click on the "Install" button next to the CodebaseMD extension
11+
12+
## 2. Manual Installation via VSIX
13+
14+
1. Download the latest `.vsix` file from the [releases section](https://github.com/alpha912/codebase-md/releases) of the GitHub repository
15+
2. Open Visual Studio Code
16+
3. Go to the Extensions view
17+
4. Click on the "..." (More Actions) button in the top-right corner of the Extensions view
18+
5. Select "Install from VSIX..."
19+
6. Navigate to the downloaded `.vsix` file and select it
20+
7. Click "Install"
21+
22+
After installation, you may need to reload Visual Studio Code for the extension to activate.
23+
24+
## Verifying Installation
25+
26+
To verify that CodebaseMD has been installed correctly:
27+
28+
1. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
29+
2. Type "CodebaseMD"
30+
3. You should see the commands "Export Codebase as Markdown" and "Export Selected as Markdown" in the list
31+
32+
If you encounter any issues during installation, please refer to the [Troubleshooting](./troubleshooting.md) guide or [open an issue](https://github.com/alpha912/codebase-md/issues) on GitHub.

‎docs/troubleshooting.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Troubleshooting
2+
3+
This guide aims to help you resolve common issues you might encounter while using CodebaseMD. If you're experiencing a problem not listed here, please [open an issue](https://github.com/alpha912/codebase-md/issues) on GitHub.
4+
5+
## Common Issues and Solutions
6+
7+
### 1. Extension Not Appearing in VS Code
8+
9+
**Problem**: After installation, you can't find CodebaseMD in the extensions list or command palette.
10+
11+
**Solutions**:
12+
- Ensure you've reloaded VS Code after installation
13+
- Check if the extension is disabled in the Extensions view
14+
- Verify that you're using a compatible version of VS Code (1.70.0 or later)
15+
16+
### 2. "Export Codebase as Markdown" Command Not Working
17+
18+
**Problem**: The command doesn't appear to do anything when invoked.
19+
20+
**Solutions**:
21+
- Make sure you have a workspace folder open in VS Code
22+
- Check the Output panel (View > Output) and select "CodebaseMD" from the dropdown for any error messages
23+
- Verify that you have write permissions in the directory where you're trying to save the Markdown file
24+
25+
### 3. Generated Markdown File is Empty or Incomplete
26+
27+
**Problem**: The exported Markdown file doesn't contain all expected content.
28+
29+
**Solutions**:
30+
- Check if your project

0 commit comments

Comments
 (0)