[WordPress] 外掛分享： Documents from Git

前言介紹

• 這款 WordPress 外掛「Documents from Git」是 2020-04-02 上架。
• 目前有 300 個安裝啟用數。
• 上一次更新是 2021-10-09，距離現在已有 1302 天。超過一年沒更新，安裝要確認版本是否可用。以及後續維護問題！
• 外掛最低要求 WordPress 5.0.0 以上版本才可以安裝。
• 外掛要求網站主機運作至少需要 PHP 版本 7.0 以上。
• 有 3 人給過評分。
• 還沒有人在論壇上發問，可能目前使用數不多，還沒有什麼大問題。

外掛協作開發者

nilsnolde | danilopinotti |

外掛標籤

Github | jupyter | markdown | Notebook | Bitbucket |

內容簡介

官方文件: https://github.com/gis-ops/wordpress-markdown-git

這個WordPress外掛讓您能夠輕鬆地從您最喜愛的遠端Git平台上發布、協作和版本控制您的[Markdown, Jupyter notebook]文檔，即使它是自己託管的。

優勢包括:

使用您喜愛的編輯器撰寫文檔，只需將其推送到您的遠端存儲庫即可立即更新您的博客
利用版本控制的威力：在不同的文章中發布不同版本的文檔，例如從除了最新的master之外的另一個分支或提交中發布
簡便地由您的讀者透過pull請求更新文檔，減少過時教程的機會

目前支援以下類型的文檔:

Markdown
Jupyter筆記本（僅限公共存儲庫）

目前支援以下平台:

Github
Bitbucket
Gitlab

使用方法

請注意，這個外掛使用Github精彩的/markdown API來呈現HTML。此處有2個注意事項:

除非授權，否則速率限制被設置為60個請求每分鐘。自v1.1.0版本以來，插件能夠靜態地緩存內容。如果這對您來說不夠靈活，您目前唯一的選擇是不使用任何快取，在這種情況下，每當有人在您的站點上打開文章時，每個文檔都會從您的提供者中拉取。然後強烈建議您創建一個Githu訪問令牌並在外掛中註冊它。然後速率限制將設置為每小時5000個請求。詳細信息請參閱全局屬性部分。
Markdown內容不可以超過400 KB，因此大約是400,000個字符包括空格。如果不是專業論文，這不應該是一個應用限制。

短代碼

本插件具有多種短代碼。

發布文檔

特定於文件的短代碼遵循一種模式[git-do平台-操作]，其中

平台可以是以下之一

github：如果您使用Github作為您的版本控制系統平台
bitbucket：如果您使用Bitbucket作為您的版本控制系統平台
gitlab：如果您使用Gitlab作為您的版本控制系統平台

操作可以是以下之一

markdown：以Github的呈現樣式呈現在您的VCS平台上托管的Markdown文件
jupyter：呈現在您的VCS平台上托管的Jupyter筆記本（僅限公共存儲庫）
checkout：呈現一個像徽章一樣的小框，帶有文檔的鏈接和最後一次提交的日期
history：呈現一個包含最後的提交日期、消息和作者的

部分

修改呈現樣式

此外，還有一個包含的短代碼[git-add-css]，它添加了一個

將CSS文件添加到您的主題根目錄中，其中包含一些類，例如class1、class2、class3
通過添加wp_enqueue_style('my-style', get_template_di

原文外掛簡介

Official documentation: https://github.com/gis-ops/wordpress-markdown-git
This WordPress Plugin lets you easily publish, collaborate on and version control your [Markdown, Jupyter notebook] documents directly from your favorite remote Git platform, even if it’s self-hosted.
The advantages are:

Write documents in your favorite editor and just push to your remote repository to update your blog instantly
Use the power of version control: publish different versions of the document in different posts, i.e. from another branch or commit than latest master
Easy to update by your readers via pull requests, minimizing the chance of stale tutorials

The following document types are currently supported:

Markdown
Jupyter notebooks (only for public repositories)

The following platforms are currently supported:

Github
Bitbucket
Gitlab

Usage
Note, this plugin uses Github’s wonderful /markdown API to render to HTML. This comes with 2 caveats:

Unless authenticated, the rate limit is set at 60 requests per minute. Since v1.1.0 the plugin is capable of statically caching content. In case that’s not dynamic enough for you, your only option currently is to not use any cache in which case every document will be pulled from your provider every time someone opens it on your site. Then it’s strongly recommended to create a Github access token and register it with the plugin. Then the rate limit will be set to 5000 requests per hour. See Global attributes section for details on how to do that.
The Markdown content cannot exceed 400 KB, so roughly 400 000 characters incl whitespace. If not a monographic dissertation, this should not be an applicable limit though.

Shortcodes
The plugin features a variety of shortcodes.
Publish documents
The document-specific shortcodes follow a pattern of [git--], where

can be one of

github: if you use Github as your VCS platform
bitbucket: if you use Bitbucket as your VCS platform
gitlab: if you use Gitlab as your VCS platform

can be one of

markdown: Render your Markdown files hosted on your VCS platform in Github’s rendering style
jupyter: Render your Jupyter notebook hosted on your VCS platfrom (only for public repositories)
checkout: Renders a small badge-like box with a link to the document and the date of the last commit
history: Renders a

section with the last commit dates, messages and authors

Manipulate rendering style
Additionally, there’s an enclosing shortcode [git-add-css] which adds a

Add a CSS file to your theme’s root folder, which contains some classes, e.g. class1, class2, class3
Enqueue the CSS file by adding wp_enqueue_style('my-style', get_template_directory_uri().'/my-style.css'); to the theme’s functions.php

Add the enclosing git-add-css shortcode to your post with the custom CSS classes in the classes attribute, e.g.:
[git-add-css classes="class1 class2 class3"]
[git-gitlab-checkout url=...]
[git-gitlab-markdown url=...]
[git-gitlab-history url=...]
[/git-add-css]

Attributes
Each shortcode takes a few attributes, indicating if it’s required for public or private repositories:
Attribute
Action
Public repo
Private repo
Type
Description
url
all except git-add-css
:ballot_box_with_check:
:ballot_box_with_check:
string
The browser URL of the document, e.g. https://github.com/gis-ops/wordpress-markdown-git/blob/master/README.md
user
all except git-add-css
:negative_squared_cross_mark:
:ballot_box_with_check:
string
The user name (not email) of an authorized user
token
all except git-add-css
:negative_squared_cross_mark:
:ballot_box_with_check:
string
The access token/app password for the authorized user
cache_ttl
all except git-add-css
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
The time in seconds that the plugin will cache, only for cache_strategy=static.
cache_strategy
all except git-add-css
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
Only static caching is implemented so far. dynamic caching is on the way!
limit
history
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
Limits the history of commits to this number. Default 5.
classes
git-add-css
:ballot_box_with_check:
:ballot_box_with_check:
string
The additional CSS classes to render the content with
Global attributes
Since most attributes will be the same across the entire system, this plugin offers the possibility to set all attributes globally except for url:
In the menu Plugins ► Plugin Editor, choose “Documents from Git” and enter your preferences in the includes/config.json.
Note, setting the attributes manually in the shortcode has always precedence over any settings in includes/config.json.
Caching
Often we need to prioritize speed when loading content and, in addition, it is very costly to fetch, load and format the content every time we need to read the content of the post.
This plugin soon offers 2 methods for caching, static and dynamic which can be set via the cache_strategy property.
Static caching (cache_strategy=static)
This is the default strategy, as it doesn’t require any user action.
The property cache_ttl sets how many seconds the content cache will keep alive.
Currently there’s no way to flush the cache manually. However, changing cache_ttl or the history limit will create a new cache.
Dynamic caching (cache_strategy=dynamic)
This is not implemented yet. See #20 for details.
Token authorization
You need to authorize via user and token if you intend to publish from a private repository. You don’t need to authorize if the repository is open.
However, keep in mind that some platforms have stricter API limits for anonymous requests which are greatly extended if you provide your credentials. So even for public repos it could make sense. And unless you use this plugin’s caching capabilities, it’s strongly recommended to register a Github access token regardless of the VCS hosting platform, see the beginning of the chapter.
How to generate the token depends on your platform:

Github: Generate a Personal Access Token following these instructions
Bitbucket: Generate a App Password following these instructions
Gitlab: Generate a Personal Access Token following these instructions

This plugin needs only Read access to your repositories. Keep that in mind when creating an access token.
Examples
We publish our own tutorials with this plugin: https://gis-ops.com/tutorials/.
Publish Markdown from Github
[git-github-markdown url="https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md"]

Publish Markdown from Github with 1 hour cache
[git-github-markdown url="https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md" cache_ttl="3600" cache_strategy="static"]

Publish Jupyter notebook from Github
[git-github-jupyter url="https://github.com/GIScience/openrouteservice-examples/blob/master/python/ortools_pubcrawl.ipynb"]

Publish from a private repository
[git-bitbucket-jupyter user=nilsnolde token=3292_2p3a_84-2af url="https://bitbucket.org/nilsnolde/test-wp-plugin/src/master/README.md"]

Display last commit and document URL from Bitbucket
[git-bitbucket-checkout url="https://bitbucket.org/nilsnolde/test-wp-plugin/src/master/README.md"]

Display commit history from Gitlab
git-gitlab-history limit=5 url="https://gitlab.com/nilsnolde/esy-osm-pbf/-/blob/master/README.md"]

Use additional CSS classes to style
The following example will put a dashed box around the whole post:
`

[git-add-css classes=”md-dashedbox”]
[git-github-checkout url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[git-github-markdown url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[git-github-history url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[/git-add-css]
`
With the following CSS file contents enqueued to your theme:
`css

div.md_dashedbox {
position: relative;
font-size: 0.75em;
border: 3px dashed;
padding: 10px;
margin-bottom:15px
}
div.md_dashedbox div.markdown-github {
color:white;
line-height: 20px;
padding: 0px 5px;
position: absolute;
background-color: #345;
top: -3px;
left: -3px;
text-transform:none;
font-size:1em;
font-family: “Helvetica Neue”,Helvetica,Arial,sans-serif;
}
`

各版本下載點

• 方法一：點下方版本號的連結下載 ZIP 檔案後，登入網站後台左側選單「外掛」的「安裝外掛」，然後選擇上方的「上傳外掛」，把下載回去的 ZIP 外掛打包檔案上傳上去安裝與啟用。
• 方法二：透過「安裝外掛」的畫面右方搜尋功能，搜尋外掛名稱「Documents from Git」來進行安裝。

（建議使用方法二，確保安裝的版本符合當前運作的 WordPress 環境。

---

1.0.0 | 1.0.1 | 1.0.2 | 1.1.0 | 1.1.1 | 2.0.0 | 2.0.1 | 2.1.0 | 2.2.0 | trunk |

延伸相關外掛（你可能也想知道）

• WP Pusher Slack Notifications 》WP Pusher 可讓您直接從 GitHub 和 Bitbucket 安裝和更新 WordPress 插件和佈景主題。此外掛會在每次部署後透過 Slack 通知您。, 當您將某些東西推送到 GitHu...。
• GitHub & BitBucket Project Lister 》這是一個 WordPress 外掛，它會列出你從 Github 或 Bitbucket（或兩者）獲得的開源專案列表。你可以把它們插入到標準文章或頁面中，或將它們插入到側邊欄中。...。
• WP-Git-Embed 》嵌入 GitHub、Gist 或 Bitbucket 的檔案。, 參考: https://github.com/gbaptista/wp-git-embed。
• WP Bitbucket 》使用簡碼從 Bitbucket 專案頁面嵌入區塊 (專案摘要、最近活動等)。, 如何使用, 這兩個簡碼可以在您的文章或頁面中使用：, , [wp-bitbucket user=”使用...。
• WB Embed Code 》這是一款由WP Bucket外掛程式開發的簡單外掛程式，可透過短碼在WordPress文章中嵌入Bitbucket程式碼。 。
• PCSH (PastaCode and SyntaxHighlighter) 》使用基於 Pastacode 外掛的 PCSH，您可以輕鬆地在文章中加入代碼，並搭配 SyntaxHighlighter js-library，呈現絕佳的語法高亮效果。, 您可以在文章編輯器中插...。
• Front Page to Category 》這是一個 WordPress 外掛，可以使你的首頁連結跳轉至文章的分類頁面，而非實際文章頁面。, 這對於增加頁面瀏覽量（和廣告展示次數），讓網站更像傳統報紙非常...。
• Bitbucket Issues Plugin 》這個 WordPress 外掛可以從一個 bitbucket.org 使用者擁有的所有程式庫，彙總問題(issue)清單並顯示為列表。, 目前採用基於 shortcode 的方式進行操作。, 歡...。
• Bitbucket Issue Manager 》這是什麼？, 這個外掛只是為了在 WordPress 儀表板內提供一個簡單的解決方案，讓您檢查專案中暫停和已完成的問題或任務。然而，我很快會增加一些額外的功能，...。
• WP Bucket 》這是一個輕量級的 WordPress 外掛程式，可使用 "Login by Bitbucket" 系統幫助您登入您的網站，並允許開發人員使用 Bitbucket API 在外掛程式或佈景主題中運...。