feat: add custom output file naming option and demo GIF

Author: 3choff

.vscodeignore

@@ -13,6 +13,7 @@ vsc-extension-quickstart.md
 images/**
 node_modules/**
 changes.txt
+media/demo.gif
 
 # Keep only essential Puppeteer files
 !node_modules/puppeteer-core/lib/cjs/**

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## [1.4.1] - 2024-11-27
+
+### Added
+- Custom output file naming option in UI
+- Added demo GIF to README for better feature visualization
+
 ## [1.3.0] - 2024-11-24
 
 ### Added

README.md

@@ -1,6 +1,10 @@
-# Docs Miner VSCode Extension
+# Docs Miner
 
-This extension allows you to generate markdown documentation from web pages and GitHub repositories using either the Jina AI Reader API or a browser-based method.
+A VSCode extension that generates markdown documentation from web pages and GitHub repositories.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/3choff/docs-miner/main/media/demo.gif" width="800" alt="Demo">
+</p>
 
 If you find Docs Miner useful, please consider leaving a star ⭐ on github repository or buying me a [coffee](https://ko-fi.com/3choff) to keep me motivated to work on this project.
 
@@ -25,8 +29,7 @@ If you find Docs Miner useful, please consider leaving a star ⭐ on github repo
 2. Enter the URL you want to generate documentation from:
    - For websites: any web URL (e.g., https://example.com)
    - For GitHub: repository URL (e.g., https://github.com/username/repo) or specific directory (e.g., https://github.com/username/repo/tree/main/docs)
-3. Specify the output folder for the generated documentation
-4. Adjust the crawling depth using the slider:
+3. Adjust the crawling depth using the slider:
    - For websites:
      - Depth 1: Only the entered page
      - Depth 2: The entered page and links at the same directory level
@@ -39,9 +42,11 @@ If you find Docs Miner useful, please consider leaving a star ⭐ on github repo
      - Depth 3: Root + two directory levels
      - Depth 4: Root + three directory levels
      - Depth 5: Root + four directory levels
-5. Click "Start Crawling" to begin
-6. Monitor the progress in real-time
-7. Use the "Stop Crawling" button if you want to end the process early
+4. Specify the file name for the generated documentation. If not specified, the URL will be used instead.
+5. Specify the output folder for the generated documentation. If not specified, the current workspace folder will be used.
+6. Click "Start Crawling" to begin
+7. Monitor the progress in real-time
+8. Use the "Stop Crawling" button if you want to end the process early
 
 The markdown file will be automatically created in your specified output folder and opened for viewing.
 
@@ -100,3 +105,10 @@ Choose one of the following installation methods:
 ## Author
 - [3choff](https://github.com/3choff)
 
+## Contributing
+Feedback and contributions are welcome. If you encounter any issues or have suggestions for improvements, please create a new [issue](https://github.com/3choff/docs-miner/issues) on the GitHub repository.
+
+If you'd like to contribute to the development of the extension, feel free to submit a pull request with your changes.
+
+## License
+This extension is licensed under the [MIT License](https://github.com/3choff/docs-miner/blob/main/LICENSE).

media/demo.gif

@@ -28,10 +28,13 @@
     <div class="section-container">
         <div class="section-label">File Settings</div>
         <div class="settings">
-        <label class="checkbox-container">
+            <label class="checkbox-container">
                 <input type="checkbox" id="autoOpenFile" />
                 <span class="checkbox-label">Auto-open the output file</span>
             </label>
+            <div class="file-input">
+                <input type="text" id="outputFileName" placeholder="File name (optional)" />
+            </div>
             <div class="folder-input">
                 <input type="text" id="outputFolder" placeholder="Output folder (optional)" />
             </div>

media/webview/index.html

@@ -9,7 +9,8 @@ const ELEMENTS = {
     status: document.getElementById('status'),
     autoOpenFile: document.getElementById('autoOpenFile'),
     outputFolder: document.getElementById('outputFolder'),
-    crawlerMethod: document.getElementById('crawlerMethod')
+    crawlerMethod: document.getElementById('crawlerMethod'),
+    outputFileName: document.getElementById('outputFileName')
 };
 
 const DEPTH_DESCRIPTIONS = {
@@ -84,6 +85,7 @@ ELEMENTS.startButton.addEventListener('click', () => {
         url,
         depth: parseInt(ELEMENTS.depthSlider.value),
         outputFolder: ELEMENTS.outputFolder.value.trim(),
+        outputFileName: ELEMENTS.outputFileName.value.trim(),
         method: ELEMENTS.crawlerMethod.value
     });
 });

media/webview/main.js

@@ -174,6 +174,7 @@ button:disabled {
     height: 80px;
     display: flex;
     align-items: center;
+    white-space: pre-line;
 }
 
 .error {
@@ -230,16 +231,9 @@ input[type="checkbox"]:checked::after {
     transform: rotate(45deg);
 }
 
-.folder-input {
-    margin-top: 10px;
-}
-
-.folder-input input {
+.folder-input input, .file-input input {
     width: 100%;
     padding: 5px;
-    border: 1px solid var(--vscode-input-border);
-    background: var(--vscode-input-background);
-    color: var(--vscode-input-foreground);
 }
 
 .feedback {

media/webview/styles.css

@@ -2,7 +2,7 @@
   "name": "docs-miner",
   "displayName": "Docs Miner",
   "description": "Generate markdown documentation from web pages and GitHub repositories",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "publisher": "3choff",
   "icon": "media/icon.png",
   "repository": {
@@ -13,6 +13,9 @@
     "vscode": "^1.80.0"
   },
   "categories": [
+    "Education",
+    "Programming Languages",
+    "Snippets",
     "Other"
   ],
   "activationEvents": [

package-lock.json

@@ -50,11 +50,12 @@ export class ViewProvider implements vscode.WebviewViewProvider {
                         url: data.url,
                         depth: data.depth,
                         method: data.method,
-                        outputFolder: data.outputFolder
+                        outputFolder: data.outputFolder,
+                        outputFileName: data.outputFileName
                     };
 
                     try {
-                        const outputPath = this.fileService.createOutputPath(options.url, options.outputFolder);
+                        const outputPath = this.fileService.createOutputPath(options.url, options.outputFolder, options.outputFileName);
                         await this.crawlerService.crawl(options, webviewView.webview);
                     } catch (error) {
                         const errorMessage = error instanceof Error ? error.message : String(error);

package.json

@@ -24,7 +24,7 @@ export class FileService implements IFileService {
         }
     }
 
-    public createOutputPath(baseUrl: string, outputFolder?: string): string {
+    public createOutputPath(baseUrl: string, outputFolder?: string, outputFileName?: string): string {
         let outputPath = this.workspaceFolder;
         if (outputFolder) {
             outputPath = path.join(this.workspaceFolder, outputFolder);
@@ -33,19 +33,24 @@ export class FileService implements IFileService {
             }
         }
 
-        const urlParts = new URL(baseUrl);
-        let urlPath = urlParts.pathname.replace(/\//g, '-');
-        urlPath = urlPath.replace(/^-|-$/g, '');
-        if (urlPath === '') urlPath = 'home';
-
-        const queryString = urlParts.search.replace(/[?&]/g, '-').replace(/[=]/g, '-');
-        const sanitizedQuery = queryString ? `-${queryString.replace(/^-|-$/g, '')}` : '';
-
-        const fileName = `${urlParts.hostname}${urlPath}${sanitizedQuery}-docs.md`
-            .toLowerCase()
-            .replace(/[^a-z0-9\-\.]/g, '-')
-            .replace(/-+/g, '-')
-            .substring(0, 255);
+        let fileName: string;
+        if (outputFileName) {
+            fileName = outputFileName.endsWith('.md') ? outputFileName : `${outputFileName}.md`;
+        } else {
+            const urlParts = new URL(baseUrl);
+            let urlPath = urlParts.pathname.replace(/\//g, '-');
+            urlPath = urlPath.replace(/^-|-$/g, '');
+            if (urlPath === '') urlPath = 'home';
+
+            const queryString = urlParts.search.replace(/[?&]/g, '-').replace(/[=]/g, '-');
+            const sanitizedQuery = queryString ? `-${queryString.replace(/^-|-$/g, '')}` : '';
+
+            fileName = `${urlParts.hostname}${urlPath}${sanitizedQuery}.md`
+                .toLowerCase()
+                .replace(/[^a-z0-9\-\.]/g, '-')
+                .replace(/-+/g, '-')
+                .substring(0, 255);
+        }
 
         this.outputFile = path.join(outputPath, fileName);
         return this.outputFile;

src/ViewProvider.ts

@@ -5,6 +5,7 @@ export interface CrawlOptions {
     depth: number;
     method: 'api' | 'browser';
     outputFolder?: string;
+    outputFileName?: string;
 }
 
 export interface CrawlStats {
@@ -35,6 +36,6 @@ export interface IContentProcessor {
 
 export interface IFileService {
     saveContent(content: string, append?: boolean): Promise<void>;
-    createOutputPath(baseUrl: string, outputFolder?: string): string;
+    createOutputPath(baseUrl: string, outputFolder?: string, outputFileName?: string): string;
     getOutputFile(): string | undefined;
 }

src/services/FileService.ts

@@ -39,7 +39,10 @@ module.exports = {
       patterns: [
         {
           from: 'media',
-          to: 'media'
+          to: 'media',
+          globOptions: {
+            ignore: ['**/*.gif']
+          }
         }
       ]
     })