在文章中嵌入程式的幾個推薦方式

避免讓程式碼以螢幕截圖或段落文字在文章中呈現

Photo by chuttersnap on Unsplash

Every developer should be blogging.

How to display code blocks in Medium 一文談起。

在有效學習或者成功面試的訣竅中,新鮮人、初學者或轉職者時常被鼓勵要寫作部落格,不論是摘錄技術文件重點、學習筆記甚至歷程心得都能有效幫助學習與面試。這篇文章我們要簡介一下如何在受到廣大設計師與工程師社群歡迎的部落格平台 Medium,展示自己寫的程式碼與輸出結果。

避免使用螢幕截圖或段落文字

在任何的部落格平台上面寫作程式相關的文章,都要避免使用螢幕截圖或段落文字來呈現程式碼,因為截圖無法讓讀者複製、段落文字欠缺合適的 highlight 和縮排格式,不論是行內程式碼 print(“Hello Python”)、程式碼區塊:

def say_hello():
return “Hello Python”

或者螢幕截圖:

使用螢幕截圖

都會讓文章的可讀性與美觀度大為下降。

使用 Medium 的程式碼標註

Medium 提供與 Markdown 相同的語法來標註行內程式碼與程式碼區塊,分別是一個 backtick(`)符號和三個 backtick(```)符號,因此行內程式碼可以寫為 而程式碼區塊可以寫為:

def say_hello():
return "Hello Python"

使用 Medium 的嵌入(Embed)功能

Medium 部落格平台受到廣大設計師與工程師社群喜愛的功能之一就是具備簡易的嵌入(Embed)功能,就好像是網頁工程師使用的 標籤一樣,能夠將其他網站的資源嵌入到文章之中,而不需要讓讀者點選超連結切換至另外一個頁籤或者視窗。Medium 寫作者只需要將其他網站的資源連結貼到文章中即可完成嵌入,像是在文中嵌入 YouTube 影片時讀者並不需要切換至 YouTube 視窗觀賞。

Hans Rosling’s 200 Countries, 200 Years, 4 Minutes — The Joy of Stats — BBC Four

嵌入 GitHub 的 gists

With gists, you can share single files, parts of files, and full applications with other people.

GitHub 提供的 gists 服務可以讓使用者即時分享程式碼與檔案,只要在新增選單中點選 New gist 即可:

在新增選單中點選 New gist

寫作欲嵌入的程式碼,並且給予對應的副檔名,就可以獲得適當的程式碼 highlight,然後點選 Create public gist:

寫作欲嵌入的程式碼,並且給予對應的副檔名

建立出 public gist 之後會獲得一個 gist 的頁面,將該頁面連結貼入到文章中,就完成程式碼嵌入。

建立出 public gist 之後會獲得一個 gist 的頁面

GitHub gists 也提供檔案的嵌入,對於使用 Jupyter Notebook 作為開發環境的資料科學家可是天大的好消息,表示著可以將筆記本中的輸入與輸出都呈現在 Medium 文章中,只需要使用任意的文字編輯器將 .ipynb 的筆記本檔案開啟並且將 .ipynb 中的內容全選複製貼上至 gists 中就可以在 Medium 文章中顯示 Jupyter Notebook 的程式碼與輸出樣式!

使用任意的文字編輯器將 .ipynb 的筆記本檔案開啟
將 .ipynb 中的內容全選複製貼上至 gists 中

嵌入 Repl.it

Repls are the workspaces that Repl.it users interface with whenever they use the app.

Repl.it 提供在瀏覽器上互動撰寫程式並且查看輸出的環境,提供超過 40 種程式語言的互動環境,涵蓋基本的檔案、Script 與 Console 介面,使用者可以在登入後於主畫面右下角點選新增 repl:

於主畫面右下角點選新增 repl

接著選取 repl 的程式語言:

選取 repl 的程式語言

建立出 repl 之後會獲得涵蓋檔案、編輯區與 Console 的頁面,將該頁面連結貼入到文章中,就完成程式碼嵌入。

建立出 repl 之後就可以分享連結

嵌入 Codepen 或 JSFiddle

如果是與網頁開發相關的文章,則可以參考 CodepenJSFiddle 這兩個網站,他們提供在瀏覽器上測試網頁應用程式服務,如果我們希望同時讓讀者看到 HTML、CSS、JavaScript 與成果,這將可以獲得最棒的閱讀體驗。

首先我們試用 Codepen:

We focus primarily on front-end languages like HTML, CSS, JavaScript, and preprocessing syntaxes that turn into those things.

Create a New Pen

建立出 pen 之後會獲得涵蓋 HTML、CSS、JavaScript 與成果的頁面,將內容存檔後該頁面連結即可貼入到文章中,完成程式碼嵌入。

建立出 pen 之後就可以分享連結

最後是 JSFiddle:

JSFiddle is for: Demos for docs, Bug reporting (test-case) for Github Issues, Presenting code answers on Stack Overflow, Live code collaboration, Code snippets hosting, … or just your humble code playground.

建立出 JSFiddle 之後會獲得涵蓋 HTML、CSS、JavaScript 與成果的頁面,將內容存檔後該頁面連結即可貼入到文章中,完成程式碼嵌入。

建立出 JSFiddle 之後就可以分享連結

小結

不論是 GitHub gistsRepl.itCodepenJSFiddle 都必須要註冊成為使用者才能夠應用所提供的服務,基本功能與公開的程式都不需要付費,這篇文章的要點有:

  • 避免使用螢幕截圖段落文字表達程式

推薦的程式嵌入可以依照不同需求選擇以下方式:


如果您喜歡這篇文章,請多按下方的「拍手」圖像幾次、分享到社群網站以及訂閱 Pyradise追蹤更多 Python 資訊,請關注 Pyradise 的臉書粉絲專頁!🙏想看影音教學?🎥
我們將在 Pyradise 的 Youtube 頻道,定期跟大家直播分享相關心得!
訂閱我們!👇👇👇

Pyradise

在 Py 樂園輕鬆學習 Python。

郭耀仁 Yao-Jen Kuo

Written by

Could that data be any tidier? It is always nice to meet a data enthusiast / 2:43 marathon runner.

Pyradise

Pyradise

在 Py 樂園輕鬆學習 Python。