vaakash

<p>Git it Write allows to publish the markdown files present in a GitHub repository to your WordPress site. So with this plugin, whenever the files are added, updated in the repository the WordPress post will be added, updated accordingly.</p>
<p>This plugin is inspired from static site generators like <code>Jekyll</code>, <code>Next.js</code>, <code>Gatsby.js</code> on how content is written is markdown. This is a similar idea for WordPress where markdown files are parsed from GitHub and published as posts.</p>
<p>👓 <strong>Live example:</strong> <a href="https://github.com/vaakash/aakash-web" rel="nofollow ugc">Source github repository</a> (<code>/docs/</code> folder) to <a href="https://www.aakashweb.com/docs/" rel="nofollow ugc">Posts published</a></p>
<p>⚡ <strong>Getting started:</strong> <a href="https://www.aakashweb.com/docs/git-it-write/getting-started/" rel="nofollow ugc">Get started</a> with Git it write. Learn how to write <code>.md</code> files and publish posts on WordPress.</p>
<p>This allows people to collaborate with the post, share edits and suggestions in GitHub which when pulled the WordPress post will be updated automatically.</p>
<p>If a repository has files in the below structure,</p>
<pre><code>docs/
    guide/
        introduction.md
        getting-started.md
help/
    faq.md
</code></pre>
<p>Then below posts will be created like below (if permalinks are configured and the post type supports “hierarchy” i.e creating posts level by level (example: pages))</p>
<pre><code>https://example.com/docs/guide/introduction/
https://example.com/docs/guide/getting-started/
https://example.com/help/faq/
</code></pre>
<h3>🎲 What is the use of this plugin ?</h3>
<ul>
<li>Publish posts using the files in your GitHub repository.</li>
<li>Write your posts in Markdown format.</li>
<li>Write your posts on your desktop application (Notepad++, Sublime Text, Visual studio code).</li>
<li>Collaborate, involve communities on the files in GitHub and publish them on WordPress.</li>
<li>All the advantages of Git and it’s version management system.</li>
</ul>
<h3>🚀 Some use cases</h3>
<ul>
<li>Can be used for documentation posts, FAQs, Wikis etc.</li>
<li>Write blog posts.</li>
<li>Any articles which may need community involvement.</li>
</ul>
<h3>✨ Features</h3>
<ul>
<li>Markdown will be processed and post will be published as HTML.</li>
<li>Images used in the source file will be uploaded to WordPress.</li>
<li>Relative links are supported.</li>
<li>Set post properties like post status, title, order, category, tags etc, in the source file itself.</li>
<li>Webhook support (whenever repository is changed, it updates the plugin to pull the latest changes and publish the posts)</li>
<li>Add multiple repositories.</li>
<li>Publish to any post type.</li>
<li>Posts are published in hierarchial manner if they are under folders. Example: a file <code>dir1/hello.md</code> will be posted as <code>dir1/hello/</code> in WordPress if the post type supports hierarchy.</li>
<li>Support for post metadata like setting tags, categories, custom fields.</li>
</ul>
<h3>ℹ Note</h3>
<ul>
<li>Only Markdown files will be pulled and published right now</li>
<li>Posts won’t be deleted when it’s source file is deleted on GitHub.</li>
<li>It is preferred to have a permalink structure.</li>
<li>It is preferred to select a post type which supports hierarchy.</li>
<li>Images have to present only in <code>_images</code> folder in the repository root. Markdown files have to relatively use them in the file.</li>
</ul>
<h3>🥗 Recommendation</h3>
<p>It is recommended that a permalink structure is enabled in the WordPress site so that, if you have file under <code>docs/reference/my-post.md</code> then a post is published like <code>https://example.com/docs/reference/my-post/</code>. This will be the result when post type has hierarchy support. They will be posted level by level for every folder in the repository. The folder’s post will be taken from the <code>index.md</code> file if exists under that folder.</p>
<h3>🏃‍♂️ Using the plugin</h3>
<ol>
<li>Have a GitHub repository where all the source files (markdown files) are maintained (organized in folders if needed the exact structure)</li>
<li>In the plugin settings page, click add a new repository.</li>
<li>Enter the details of the repository to pull the posts from and under what post type to publish them.</li>
<li>Save the settings</li>
<li>Click “Pull the posts” and then “Pull only” changes. This will publish posts for all the markdown files.</li>
<li>To automatically update posts whenever repository is updated, configure webhook as mentioned in the settings page.</li>
</ol>
<h3>Links</h3>
<ul>
<li><a href="https://www.aakashweb.com/docs/git-it-write/" rel="nofollow ugc">Documentation</a></li>
<li><a href="https://www.aakashweb.com/forum/" rel="nofollow ugc">Support forum/Report bugs</a></li>
<li><a href="https://www.paypal.me/vaakash/" rel="nofollow ugc">Donate</a></li>
<li><a href="https://github.com/vaakash/git-it-write" rel="nofollow ugc">Contribute on GitHub</a></li>
</ul>


Git it Write – Write posts from GitHub

You will like it !

Publish markdown files present in a GitHub repository as posts to WordPress automatically

Danilo Pinotti

nilsnolde

<p>Official documentation: https://github.com/gis-ops/wordpress-markdown-git</p>
<p>This WordPress Plugin lets you easily publish, collaborate on and version control your [<strong>Markdown, Jupyter notebook</strong>] documents directly from your favorite remote Git platform, <strong>even if it’s self-hosted</strong>.</p>
<p>The advantages are:</p>
<ul>
<li>Write documents in your favorite editor and just push to your remote repository to update your blog instantly</li>
<li>Use the power of version control: publish different versions of the document in different posts, i.e. from another branch or commit than latest <code>master</code></li>
<li>Easy to update by your readers via pull requests, minimizing the chance of stale tutorials</li>
</ul>
<p>The following document types are currently supported:</p>
<ul>
<li>Markdown</li>
<li>Jupyter notebooks (<strong>only for public repositories</strong>)</li>
</ul>
<p>The following platforms are currently supported:</p>
<ul>
<li>Github</li>
<li>Bitbucket</li>
<li>Gitlab</li>
</ul>
<h3>Usage</h3>
<p><strong>Note</strong>, this plugin uses Github’s wonderful <a href="https://developer.github.com/v3/markdown/" rel="nofollow ugc"><code>/markdown</code> API</a> to render to HTML. This comes with 2 caveats:</p>
<ol>
<li>Unless authenticated, the rate limit is set at 60 requests per minute. Since v1.1.0 the plugin is capable of statically <a href="#caching" rel="nofollow ugc">caching content</a>. 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 <strong>strongly recommended</strong> 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 <a href="#global-attributes" rel="nofollow ugc">Global attributes section</a> for details on how to do that.</li>
<li>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.</li>
</ol>
<h3>Shortcodes</h3>
<p>The plugin features a variety of shortcodes.</p>
<h4>Publish documents</h4>
<p>The document-specific shortcodes follow a pattern of <code>[git-<platform>-<action>]</code>, where</p>
<ul>
<li><code><platform></code> can be one of
<ul>
<li><code>github</code>: if you use Github as your VCS platform</li>
<li><code>bitbucket</code>: if you use Bitbucket as your VCS platform</li>
<li><code>gitlab</code>: if you use Gitlab as your VCS platform</li>
</ul>
</li>
<li><code><action></code> can be one of
<ul>
<li><code>markdown</code>: Render your Markdown files hosted on your VCS platform in Github’s rendering style</li>
<li><code>jupyter</code>: Render your Jupyter notebook hosted on your VCS platfrom (<strong>only for public repositories</strong>)</li>
<li><code>checkout</code>: Renders a small badge-like box with a link to the document and the date of the last commit</li>
<li><code>history</code>:  Renders a <code><h2></code> section with the last commit dates, messages and authors</li>
</ul>
</li>
</ul>
<h4>Manipulate rendering style</h4>
<p>Additionally, there’s an enclosing shortcode <code>[git-add-css]</code> which adds a <code><div id="git-add-css" class="<classes_attribute>"</code> to wrap its contents. That way you can manipulate the style freely with additional CSS classes. Follow these steps:</p>
<ol>
<li>Add a CSS file to your theme’s root folder, which contains some classes, e.g. <code>class1</code>, <code>class2</code>, <code>class3</code></li>
<li>Enqueue the CSS file by adding <code>wp_enqueue_style('my-style', get_template_directory_uri().'/my-style.css');</code> to the theme’s <code>functions.php</code></li>
<li>
<p>Add the enclosing <code>git-add-css</code> shortcode to your post with the custom CSS classes in the <code>classes</code> attribute, e.g.:</p>
<p><code>[git-add-css classes="class1 class2 class3"]<br />
[git-gitlab-checkout url=...]<br />
[git-gitlab-markdown url=...]<br />
[git-gitlab-history url=...]<br />
[/git-add-css]</code></p>
</li>
</ol>
<h3>Attributes</h3>
<p>Each shortcode takes a few attributes, indicating if it’s required for public or private repositories:</p>
<p>  Attribute<br />
  Action<br />
  Public repo<br />
  Private repo<br />
  Type<br />
  Description</p>
<p>  <code>url</code><br />
  all except <code>git-add-css</code><br />
  :ballot_box_with_check:<br />
  :ballot_box_with_check:<br />
  string<br />
  The browser URL of the document, e.g. https://github.com/gis-ops/wordpress-markdown-git/blob/master/README.md</p>
<p>  <code>user</code><br />
  all except <code>git-add-css</code><br />
  :negative_squared_cross_mark:<br />
  :ballot_box_with_check:<br />
  string<br />
  The <strong>user name</strong> (not email) of an authorized user</p>
<p>  <code>token</code><br />
  all except <code>git-add-css</code><br />
  :negative_squared_cross_mark:<br />
  :ballot_box_with_check:<br />
  string<br />
  The access token/app password for the authorized user</p>
<p>  <code>cache_ttl</code><br />
  all except <code>git-add-css</code><br />
  :negative_squared_cross_mark:<br />
  :negative_squared_cross_mark:<br />
  integer<br />
  The time in seconds that the plugin will cache, <strong>only for <code>cache_strategy=static</code></strong>.</p>
<p>  <code>cache_strategy</code><br />
  all except <code>git-add-css</code><br />
  :negative_squared_cross_mark:<br />
  :negative_squared_cross_mark:<br />
  integer<br />
  Only <code>static</code> caching is implemented so far. <code>dynamic</code> caching is on the way!</p>
<p>  <code>limit</code><br />
  <code>history</code><br />
  :negative_squared_cross_mark:<br />
  :negative_squared_cross_mark:<br />
  integer<br />
  Limits the history of commits to this number. Default 5.</p>
<p>  <code>classes</code><br />
  <code>git-add-css</code><br />
  :ballot_box_with_check:<br />
  :ballot_box_with_check:<br />
  string<br />
  The additional CSS classes to render the content with</p>
<h4>Global attributes</h4>
<p>Since most attributes will be the same across the entire system, this plugin offers the possibility to set all attributes globally except for <code>url</code>:</p>
<p>In the menu <em>Plugins</em> ► <em>Plugin Editor</em>, choose “Documents from Git” and enter your preferences in the <code>includes/config.json</code>.</p>
<p><strong>Note</strong>, setting the attributes manually in the shortcode has always precedence over any settings in <code>includes/config.json</code>.</p>
<h4>Caching</h4>
<p>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.</p>
<p>This plugin soon offers 2 methods for caching, <code>static</code> and <code>dynamic</code> which can be set via the <code>cache_strategy</code> property.</p>
<p>Static caching (<code>cache_strategy=static</code>)</p>
<p>This is the default strategy, as it doesn’t require any user action.</p>
<p>The property <code>cache_ttl</code> sets how many <strong>seconds</strong> the content cache will keep alive.</p>
<p>Currently there’s no way to flush the cache manually. However, changing <code>cache_ttl</code> or the history <code>limit</code> will create a new cache.</p>
<p>Dynamic caching (<code>cache_strategy=dynamic</code>)</p>
<p><strong>This is not implemented yet</strong>. See <a href="https://github.com/gis-ops/wordpress-markdown-git/issues/20" rel="nofollow ugc">#20</a> for details.</p>
<h4><code>Token</code> authorization</h4>
<p>You <strong>need to</strong> authorize via <code>user</code> and <code>token</code> if you intend to publish from a private repository. You <strong>don’t need to</strong> authorize if the repository is open.</p>
<p>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 <a href="#caching" rel="nofollow ugc">caching capabilities</a>, it’s strongly recommended to register a Github access token regardless of the VCS hosting platform, see the <a href="#usage" rel="nofollow ugc">beginning of the chapter</a>.</p>
<p>How to generate the <code>token</code> depends on your platform:</p>
<ul>
<li>Github: Generate a Personal Access Token following <a href="https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line" rel="nofollow ugc">these instructions</a></li>
<li>Bitbucket: Generate a App Password following <a href="https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html#Apppasswords-Createanapppassword" rel="nofollow ugc">these instructions</a></li>
<li>Gitlab: Generate a Personal Access Token following <a href="https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token" rel="nofollow ugc">these instructions</a></li>
</ul>
<p>This plugin needs only <strong>Read access</strong> to your repositories. Keep that in mind when creating an access token.</p>
<h3>Examples</h3>
<p>We publish our own tutorials with this plugin: https://gis-ops.com/tutorials/.</p>
<h4>Publish Markdown from Github</h4>
<pre><code>[git-github-markdown url="https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md"]
</code></pre>
<h4>Publish Markdown from Github with 1 hour cache</h4>
<pre><code>[git-github-markdown url="https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md" cache_ttl="3600" cache_strategy="static"]
</code></pre>
<h4>Publish Jupyter notebook from Github</h4>
<pre><code>[git-github-jupyter url="https://github.com/GIScience/openrouteservice-examples/blob/master/python/ortools_pubcrawl.ipynb"]
</code></pre>
<h4>Publish from a private repository</h4>
<pre><code>[git-bitbucket-jupyter user=nilsnolde token=3292_2p3a_84-2af url="https://bitbucket.org/nilsnolde/test-wp-plugin/src/master/README.md"]
</code></pre>
<h4>Display last commit and document URL from Bitbucket</h4>
<pre><code>[git-bitbucket-checkout url="https://bitbucket.org/nilsnolde/test-wp-plugin/src/master/README.md"]
</code></pre>
<h4>Display commit history from Gitlab</h4>
<pre><code>git-gitlab-history limit=5 url="https://gitlab.com/nilsnolde/esy-osm-pbf/-/blob/master/README.md"]
</code></pre>
<h4>Use additional CSS classes to style</h4>
<p>The following example will put a dashed box around the whole post:</p>
<pre><code>`
</code></pre>
<p>[git-add-css classes=”md-dashedbox”]<br />
    [git-github-checkout url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]<br />
    [git-github-markdown url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]<br />
    [git-github-history url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]<br />
[/git-add-css]<br />
    `</p>
<p>With the following CSS file contents enqueued to your theme:</p>
<pre><code>`css
</code></pre>
<p>div.md_dashedbox {<br />
    position: relative;<br />
    font-size: 0.75em;<br />
    border: 3px dashed;<br />
    padding: 10px;<br />
    margin-bottom:15px<br />
}</p>
<p>div.md_dashedbox div.markdown-github {<br />
    color:white;<br />
    line-height: 20px;<br />
    padding: 0px 5px;<br />
    position: absolute;<br />
    background-color: #345;<br />
    top: -3px;<br />
    left: -3px;<br />
    text-transform:none;<br />
    font-size:1em;<br />
    font-family: “Helvetica Neue”,Helvetica,Arial,sans-serif;<br />
}<br />
    `</p>


Documents from Git

With this plugin I can centralize my post reviews at github without further efforts

Very useful plugin

A plugin to inject and render files in a WordPress post or page directly from most popular Git platforms. Currently supported file types: Markdown, J …

Git it Write – Write posts from GitHub vs Documents from Git