Merge pull request #54 from lumaxis/feature/add-markdown-settings

New: Add option to configure Markdown block behavior

Author: lumaxis

CHANGELOG.md

@@ -7,6 +7,10 @@
 - Rename VS Code commands to be shorter and more concise.
     - `Copy Snippet Without Leading Indentation` is now `Copy Snippet`
     - `Copy Snippet Without Leading Indentation as Markdown Code Block` is now `Copy Snippet as Markdown Code Block`
+- Improve configuration options for Markdown code blocks
+  - Add `markdownCodeBlock.includeLanguageIdentifier` configuration option for Markdown block behavior. **This replaces `snippet-copy.addLanguageIdentifierToMarkdownBlock`**. 
+  - Allows to set whether Markdown blocks should always include the [language identifier](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks) which allows for syntax highlighting in some tools (for example github.com) but is not compatible with others (for example Slack).  
+  - The default is "`prompt`" which makes the extension always prompt when using the "Copy Snippet as Markdown Code Block" command.
 
 ## [0.2.3]
 

package-lock.json

@@ -42,10 +42,20 @@
 		"configuration": {
 			"title": "Snippet Copy",
 			"properties": {
-				"snippet-copy.addLanguageIdentifierToMarkdownBlock": {
-					"type": "boolean",
-					"default": false,
-					"description": "Add a programming language identifier to the beginning of the Markdown code block. This is incompatible with some apps, for example Slack."
+				"snippet-copy.markdownCodeBlock.includeLanguageIdentifier": {
+					"type": "string",
+					"default": "prompt",
+					"markdownDescription": "Style of the generated [fenced Markdown code block](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). By default, prompts every time a snippet is copied as a Markdown code block.",
+					"enum": [
+						"never",
+						"always",
+						"prompt"
+					],
+					"markdownEnumDescriptions": [
+						"Copy a regular fenced Markdown code block without language identifier.",
+						"Copy a fenced Markdown code block that includes the language identifier of the current document.  \nThis enables [automatic syntax highlighting](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks#syntax-highlighting) on e.g. GitHub or StackOverflow but isn't compatible with some apps, for example Slack.",
+						"Always prompt when copying a snippet as a Markdown code block whether to include the language identifier or not."
+					]
 				}
 			}
 		},
@@ -98,6 +108,7 @@
 		"eslint": "^7.3.1",
 		"glob": "^7.1.6",
 		"mocha": "^8.0.1",
+		"testdouble": "^3.13.1",
 		"typescript": "^3.9.5",
 		"vscode-test": "^1.4.0"
 	}

package.json

@@ -4,16 +4,19 @@ import { generateSnippet } from './lib/textHelpers';
 export function activate(context: ExtensionContext): void {
 	context.subscriptions.push(
 		commands.registerTextEditorCommand('snippet-copy.copySnippet', (editor) => {
-			const snippet = generateSnippet(editor.document, editor.selections, false);
-
-			void env.clipboard.writeText(snippet);
+			void generateSnippet(editor.document, editor.selections, false)
+				.then((snippet) => {
+					return env.clipboard.writeText(snippet);
+				});
 		})
 	);
+
 	context.subscriptions.push(
 		commands.registerTextEditorCommand('snippet-copy.copySnippetAsMarkdownCodeBlock', (editor) => {
-			const snippet = generateSnippet(editor.document, editor.selections, true);
-
-			void env.clipboard.writeText(snippet);
+			void generateSnippet(editor.document, editor.selections, true)
+				.then((snippet) => {
+					return env.clipboard.writeText(snippet);
+				});
 		})
 	);
 }

src/extension.ts

@@ -1,19 +1,22 @@
-import { Selection, TextDocument, workspace } from "vscode";
+import { QuickPickItem, Selection, TextDocument, window, workspace } from "vscode";
+import { ExtensionConfig, IncludeLanguageIdentifier } from "../types/config";
 import { contentOfLinesWithAdjustedIndentation, endOfLineCharacter, languageId, minimumIndentationForLineIndexes } from "./documentHelpers";
 import { lineIndexesForSelection } from "./selectionHelpers";
 
-export function generateSnippet(document: TextDocument, selections: Selection[], markdownCodeBlock = false): string {
+type MarkdownCodeBlockFlavorQuickPickItems = QuickPickItem & {
+	detail: IncludeLanguageIdentifier;
+};
+
+export async function generateSnippet(document: TextDocument, selections: Selection[], wrapInMarkdownCodeBlock = false): Promise<string> {
 	const texts: string[] = [];
 	selections.forEach(selection => {
 		texts.push(generateCopyableText(document, selection));
 	});
 
 	const snippet = texts.join(endOfLineCharacter(document));
 
-	if (markdownCodeBlock) {
-		const config = workspace.getConfiguration('snippet-copy');
-
-		return wrapTextInMarkdownCodeBlock(document, snippet, config.addLanguageIdentifierToMarkdownBlock);
+	if (wrapInMarkdownCodeBlock) {
+		return wrapTextInMarkdownCodeBlock(document, snippet, await includeLanguageIdentifier(workspace.getConfiguration('snippet-copy') as ExtensionConfig));
 	}
 
 	return snippet;
@@ -38,7 +41,42 @@ export function wrapTextInMarkdownCodeBlock(document: TextDocument, text: string
 	const eolCharacter = endOfLineCharacter(document);
 	const optionalLanguageIdentifier = addLanguageId ? languageId(document) : '';
 
-	return 	codeBlockDelimiter + optionalLanguageIdentifier + eolCharacter +
-					text + eolCharacter +
-					codeBlockDelimiter;
+	return codeBlockDelimiter + optionalLanguageIdentifier + eolCharacter +
+		text + eolCharacter +
+		codeBlockDelimiter;
+}
+
+export async function includeLanguageIdentifier(config: ExtensionConfig): Promise<boolean> {
+	let includeLanguageIdentifier = config.markdownCodeBlock.includeLanguageIdentifier;
+
+	if (includeLanguageIdentifier === 'prompt') {
+		const prompt = await promptForMarkdownCodeBlockFlavor();
+
+		if (prompt && isMarkdownCodeBlockFlavor(prompt.detail)) {
+			includeLanguageIdentifier = prompt.detail;
+		}
+	}
+	return includeLanguageIdentifier === 'always';
+}
+
+export async function promptForMarkdownCodeBlockFlavor(): Promise<MarkdownCodeBlockFlavorQuickPickItems | undefined> {
+	const quickPickItems: MarkdownCodeBlockFlavorQuickPickItems[] = [
+		{
+			label: 'Plain fenced Markdown code block',
+			detail: 'never',
+			description: 'Copy a regular fenced Markdown code block without language identifier'
+		}, {
+			label: 'Include Markdown language identifier',
+			detail: 'always',
+			description: "Copy a Markdown code block that includes the language identifier of the current document"
+		}
+	];
+	return window.showQuickPick(quickPickItems, {
+		matchOnDetail: true
+	});
+}
+
+export function isMarkdownCodeBlockFlavor(value: string | undefined): value is IncludeLanguageIdentifier {
+	const validValues: IncludeLanguageIdentifier[] = ['never', 'always'];
+	return !!value && validValues.includes(value as IncludeLanguageIdentifier);
 }

src/lib/textHelpers.ts

@@ -1,8 +1,10 @@
 import * as assert from 'assert';
 import * as path from 'path';
+import * as td from 'testdouble';
 import * as vscode from 'vscode';
 import { Position, Selection, TextDocument } from 'vscode';
-import { generateCopyableText, generateSnippet, wrapTextInMarkdownCodeBlock } from '../../../lib/textHelpers';
+import { generateCopyableText, generateSnippet, includeLanguageIdentifier, isMarkdownCodeBlockFlavor, wrapTextInMarkdownCodeBlock } from '../../../lib/textHelpers';
+import { ExtensionConfig } from '../../../types/config';
 
 const fixturesPath = '/../../../../src/test/fixtures/';
 const uri = vscode.Uri.file(
@@ -34,19 +36,19 @@ describe('Text Helpers', () => {
 	});
 
 	context('generateSnippet', () => {
-		it('generates the correct snippet for a single selection', () => {
-			assert.deepEqual(testSelection1.content, generateSnippet(document, [testSelection1.selection]));
+		it('generates the correct snippet for a single selection', async () => {
+			assert.deepEqual(testSelection1.content, await generateSnippet(document, [testSelection1.selection]));
 		});
 
-		it('generates the correct snippet for multiple selections', () => {
+		it('generates the correct snippet for multiple selections', async () => {
 			assert.deepEqual(testSelection1.content + '\n' + testSelection2.content,
-				generateSnippet(document, [testSelection1.selection, testSelection2.selection])
+				await generateSnippet(document, [testSelection1.selection, testSelection2.selection])
 			);
 		});
 
-		it('generates the correct snippet for multiple selections where one ends on the beginning of a newline', () => {
+		it('generates the correct snippet for multiple selections where one ends on the beginning of a newline', async () => {
 			assert.deepEqual(testSelection1.content + '\n' + testSelection2.content,
-				generateSnippet(document, [
+				await generateSnippet(document, [
 					new Selection(testSelection1.selection.start, new Position(5, 0)),
 					testSelection2.selection
 				])
@@ -70,17 +72,56 @@ describe('Text Helpers', () => {
 				generateCopyableText(document, testSelection3.selection)
 			);
 		});
+	});
+
+	context('wrapTextInMarkdownCodeBlock', () => {
+		it('returns the text wrapped in a Markdown code block', () => {
+			const codeSnippet = 'console.log("Yo");';
+			assert.equal(wrapTextInMarkdownCodeBlock(document, codeSnippet), '```\n' + codeSnippet + '\n```');
+		});
+
+		it('returns the wrapped text with a language identifier', () => {
+			const codeSnippet = 'console.log("Yo");';
+			assert.equal(wrapTextInMarkdownCodeBlock(document, codeSnippet, true), '```javascript\n' + codeSnippet + '\n```');
+		});
+	});
+
+	context('includeLanguageIdentifier', () => {
+		it('returns true if setting is "includeLanguageIdentifier"', async () => {
+			const config: unknown = td.object({ markdownCodeBlock: { includeLanguageIdentifier: 'always' } });
+
+			assert.strictEqual(await includeLanguageIdentifier(config as ExtensionConfig), true);
+		});
+
+		it('returns false if setting is "plain"', async () => {
+			const config: unknown = td.object({ markdownCodeBlock: { includeLanguageIdentifier: 'never' } });
+
+			assert.strictEqual(await includeLanguageIdentifier(config as ExtensionConfig), false);
+		});
+
+		it('returns false if setting is true', async () => {
+			const config: unknown = td.object({ markdownCodeBlock: { includeLanguageIdentifier: true } });
+
+			assert.strictEqual(await includeLanguageIdentifier(config as ExtensionConfig), false);
+		});
+	});
 
-		context('wrapTextInMarkdownCodeBlock', () => {
-			it('returns the text wrapped in a Markdown code block', () => {
-				const codeSnippet = 'console.log("Yo");';
-				assert.equal(wrapTextInMarkdownCodeBlock(document, codeSnippet), '```\n' + codeSnippet + '\n```');
-			});
+	context('isMarkdownCodeBlockFlavor', () => {
+		it('returns true if value is "never"', () => {
+			assert.equal(isMarkdownCodeBlockFlavor('never'), true);
+		});
 
-			it('returns the wrapped text with a language identifier', () => {
-				const codeSnippet = 'console.log("Yo");';
-				assert.equal(wrapTextInMarkdownCodeBlock(document, codeSnippet, true), '```javascript\n' + codeSnippet + '\n```');
-			});
+		it('returns true if value is "always"', () => {
+			assert.equal(isMarkdownCodeBlockFlavor('always'), true);
 		});
+
+		it('returns false if value is any other string', () => {
+			assert.equal(isMarkdownCodeBlockFlavor('prompt'), false);
+		});
+
+		it('returns false if value is undefined', () => {
+			assert.equal(isMarkdownCodeBlockFlavor(undefined), false);
+		});
+
 	});
 });

src/test/suite/lib/textHelpers.test.ts

@@ -0,0 +1,10 @@
+import { WorkspaceConfiguration } from "vscode";
+
+export type IncludeLanguageIdentifier = 'always' | 'never';
+
+export type ExtensionConfig = WorkspaceConfiguration & {
+	markdownCodeBlock: {
+		includeLanguageIdentifier: IncludeLanguageIdentifier | 'prompt'
+	};
+	addLanguageIdentifierToMarkdownBlock?: boolean;
+};