[超譯]設定vscode markdown 環境

[超譯]VS code 的 markdown

譯序

參考文件是 https://code.visualstudio.com/docs/languages/markdown
內建支援 preview (預覽)，也可多裝 extension 加強能力。
本來是想寫心得的，不小心就變超譯了。既然是超譯，就代表有些地方我會增減。有興趣還請看原文。

前言

在 Visual Studio Code 裡使用 markdown 可以非常有趣，也有很多 markdown 的特色讓你更有生產力。

markdown extension

內建的功能之外，還有一些 extension 增加功能。

譯註：這段在文章裡是動態產生一組 markdown 相關的 extension 列表，所以會是什麼會隨時間演進。

開啟預覽

要開一個預覽是用 ctrl-shift-v，會多開一個 tab (頁籤) 顯示。這個我覺得不好用，我喜歡 side by side (也就是視窗並列)的方式。按鍵是 ctrl-k v (先按 ctrl-k，然後放開，再按 v，這個不能在中文輸入法裡，如果卡在輸入法中，會抓不到 v 這個鍵) 叫出視窗並列的預覽。

使用自己的 css

可以改變預覽的樣子，當然，對於後續的編譯成 html 也有用途。要更新 "markdown.styles": [] 的設定。

例如我有一個 css 長這樣：

body {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

h1 {
    color: cornflowerblue;
}

用 File > Preferences > Workspace Settings 開啟設定 settings.json 更新裡面的內容為：

// Place your settings in this file to overwrite default and user settings.
{
    "markdown.styles": [
        "Style.css"
    ]
}

## snippets for markdown
有幾個內建的 snippets，用 ctrl-space 來驅動，這就會依語境提供一串建議。

譯註：ctrl-space 在中文輸入法啟用的時候，悲劇。

編譯成 html

VS code 整進一個 task runner 可以用它與 markdown 編譯器合作完成編譯工作。可以把 .md 檔變成 .html 檔。

1. 背後是使用 node.js 來處理，所以要安裝 node.js 之外，再加上 marked。用 npm 安裝 npm install -g marked。

2. 建立一個 md 檔。記得開啟一個「目錄」再開一個新檔案 sample.md (多餘的我不想翻…) 把底下的文字放進去：

   Hello Markdown in VS Code!
   ====================
   
   This is a simple introduction to compiling Markdown in VS Code.
   
   Things you'll need:
   
   * [node](https://nodejs.org)
   * [marked](https://www.npmjs.com/package/marked)
   * [tasks.json](/docs/editor/tasks)
   
   ## Section Title
   
   > This block quote is here for your information.
   

3. 建立 task.json。打開 Command Palette (用 ctrl-shift-p)，然後在裡打字 Configure Task Runner，然後按 enter。它會列出可能的 tasks.json 模板，選 Others，因為我們要執行外部命令。這會在你的 Workspace 的 .vscode 目錄裡產生一個 tasks.json 檔案，長成這樣：

   {
       // See http://go.microsoft.com/fwlink/?LinkId=733558
       // for the documentation about the tasks.json format
       "version": "0.1.0",
       "command": "echo",
       "isShellCommand": true,
       "args": ["Hello World"],
       "showOutput": "always"
   }
   

   因為我們要使用 marked 編譯 markdown 檔，所以要改成以下這樣：

   {
   // See http://go.microsoft.com/fwlink/?LinkId=733558
   // for the documentation about the tasks.json format
   "version": "0.1.0",
   "command": "marked",
   "isShellCommand": true,
   "args": ["sample.md", "-o", "sample.html"],
   "showOutput": "always"
   

   }

   這設定的意思是把 marked 當成一個外部任務執行者，只執行一項任務，把 markdown 檔編譯成 html 檔，它的命令是 marked sample.md -o sample.html

4. 執行建立任務。以上只是在檔案裡設定，要執行它可以按 ctrl-shift-b (Run Build Task)。此時，你應該可以看到一個增加的 sample.html 檔案出現在檔案列表裡。

   這個範例不會出現什麼問題所以執行任務完會有對應的 sample.html 被建立。

自動編譯

再進一步，想要自動編譯的話，需要多做些事。

1. 加裝 gulp npm install -g gulp gulp-markdown。多裝 gulp-markdown 會讓事情簡單一點。

2. 建立 gulp task。在 simple.md 那個目錄開新檔案 gulpfile.js。把以下內容放進去：

   var gulp = require('gulp');
   var markdown = require('gulp-markdown');
   
   gulp.task('markdown', function() {
       return gulp.src('**/*.md')
           .pipe(markdown())
           .pipe(gulp.dest(function(f) {
               return f.base;
           }));
   });
   
   gulp.task('default', function() {
       gulp.watch('**/*.md', ['markdown']);
   });
   

   以上程式會做這些事：

   1. 在 Workspace 裡看哪些檔案有變動。
   2. 把有改變的 markdown 檔案們，用 markdown 編譯器處理一遍。(gulp-markdown)
   3. 這樣我們就會有一堆名字對應的 markdown 檔與 html 檔在同一目錄裡。

3. 修改 tasks.json 以完成監視。要完整把任務整合進 VS code，還需要修改任務設定。改成以下的樣子：

   {
       "version": "0.1.0",
       "command": "gulp",
       "isShellCommand": true,
       "tasks": [
           {
               "taskName": "default",
               "isBuildCommand": true,
               "showOutput": "always",
               "isWatching": true
           }
       ]
   }
   

4. 執行 gulp Build Task。以上仍是一個檔案內的設定，要執行它要按 ctrl-shift-b (Run Build Task)。但這次我們是設定一個監視，所以 Status Bar 應該會在左手邊指示。

   現在，如果建立或改變其他的 markdown 檔，你會看到對應的 html 被產生出來或是存檔時反應改變。你也可以啟用 Auto Save 讓事情更流暢。

   如果你要停止監視，你可以按 ctrl-shift-b，然後在 message box 裡點 Terminate Running Task。或者你可以用 Command Palette (用 ctrl-shift-p 叫出來)，然後找到 terminate command。

接下來

你可以往下看的是：

• 客製化 https://code.visualstudio.com/docs/customization/overview

  更多的設定如換行，自定義的 snippets

• CSS, Less, Sass https://code.visualstudio.com/docs/languages/css

  修改自己的 CSS，VS Code 支援 CSS, Less 與 Sass 編輯。

幾個常見問答

• 有無拼字檢查？
  
  • 內建沒有，但是可以加裝 spell checking extension
• 有無支援 github 風格的 markdown？
  
  • 沒有，VS code 以支援 CommonMark 為目標，使用 markdown-it 函式庫(它實作 CommonMark 標準)。
• 上面的過程裡我在 Command Palette 找不到 Configure Task Runner 命令？
  
  • 你應該是一開始選擇開啟檔案，而不是開啟目錄。你可以用 File > Open Folder…開啟目錄，或是用命令列 cd 到目的地，再執行 code . 開啟目錄。