2016年9月20日 星期二

[超譯]設定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。

接下來

你可以往下看的是:

幾個常見問答

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

沒有留言:

張貼留言