hexo-tag-plugins

GitHub Tag Plugins for Hexo

Currently I’m working on improving my projects section by linking to some of my projects hosted on Github. One idea is to display the Github README there. Playing around with the GitHub API is fun and so I created two new Hexo Tag Plugins that I don’t want to deprive you of and that extend the Hexo Tag Plugin Collection.

  • GitHub README
  • GitHub User & Repo Card

GitHub README

Gets the README.md file from a repo and shows it in an expandable detail tag.

Usage Example:

1
{% github_readme "kristofzerbe" "hexo-tag-plugins" "README for 'hexo-tag-plugins' on GitHub" %}

Live Output:

README for 'hexo-tag-plugins' on GitHub

issues
Open in Visual Studio Code

hexo-tag-plugins

Hexo Tag Plugin Collection from kiko.io

Introduction

Hexo is a Markdown based SSG (Static Site Generator). Because the Mardown syntax is limited for good reason, Hexo has tag plugins you can use in your content to simplify and centralize complex structures, instead of writing pure HTML. For more information, see hexo.io/docs/tag-plugins.

This project is a growing collection of tag plugins that I have developed and use for my blog kiko.io. Some of them are quite simple, others are more complex, but overall maybe helpful for you.

Installation / Using

There is no automatic installation of all tag plugins via NPM or other package managers, because every tag plugin stands for itself and you can pick the one you need simply by copying the appropriate JS file into your Hexo’s script folder: THEMES / <YOUR-THEME> / SCRIPTS.

For every tag plugin in the list below I provide a Visual Studio Code Snippet to quickly insert a plugin into the content via the hotkey Ctrl+Space. To use the snippest create a new .code-snippets file in your projects .vscode folder and insert the snippets of all tag plugins you have downloaded into your project.

Parameter Description Syntax

Every tag plugin includes a description in the header how to use it. The syntax is as follows:

Syntax Description
param1 mandatory parameter
[param2] optional parameter
[param2=default] optional parameter with default value
param:(option1,option2) parameter option list to choose one option
..."value1|value2" pipe delimitered array of values

-

Plugins

-

Anchor

A simple anchor element as A- or HR-Tag as jump target for example from a Anchorlist.

Files:

Syntax:

{% anchor "anchorId" elementType:(A,HR) %}``

Parameters:

No Parameter optional/default Description
1 anchorId - String to define the anchor id
2 elementType - Type of tag to render; select out of A or HR

Usage Example:

{% anchor "my-anchor" HR  %}

Output:

<hr id="my-anchor">

VS Code Snippet:

"hexo.kiko-io.anchor": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.anchor",
  "body": [
    "{% anchor \"${1:anchorId}\" ${2|A,HR|}  %}"
  ],
  "description": "Insert kiko.io's anchor"
}

-

Anchorlist

Creates an overview of all anchors in the content with jump links.

Files:

Syntax:

{% anchorlist ..."title|anchorId" %}

Parameters:

No Parameter optional/default Description
1 ..."title|anchorId" - List of pipe separated items with referencing title and anchor id

Usage Example:

{% anchorlist
  "My First Anchor|a1"
  "My Second Anchor|a2"
%}

Output:

<ul class="anchorlist">
  <li data-anchor="#a1">
    <a href="#a1">My First Anchor</a>
  </li>
  <li data-anchor="#a2">
    <a href="#a2">My Second Anchor</a>
  </li>
</ul>

Anchorlist Example

VS Code Snippet:

"hexo.kiko-io.anchorlist": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.anchorlist",
  "body": [
    "{% anchorlist ${1:...\"title|anchorId\"} %}"
  ],
  "description": "Insert kiko.io's anchorlist"
}

-

Alertbox

Renders a iconized colored box with text for warnings or with some special information. 6 styles are provided: Exclamation, Question, Warning, Info, Success and Note.

Files:

Prequisites:

The icons are from the font FontAwesome Free Solid, you need to reference in your CSS either from your project or from a CDN. You will find such references in the file tag-alertbox.css, together with all other necessary styles.

Syntax:

{% alertbox alertType:(exclamation,question,warning,info,success,note) %}
content
{% endalertbox %}``

Parameters:

No Parameter optional/default Description
1 alertType - Type of the alert (icon and color); select out of exclamation, question, warning, info, success or note

content is not a parameter, but Markdown to render.

Usage Example:

{% alertbox warning %}
Something has failed!
{% endalertbox %}

Output:

<div class="alertbox alertbox-warning">
  <p>Something has failed!</p>
</div>

Alertbox Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#alertbox

VS Code Snippet:

"hexo.kiko-io.alertbox": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.alertbox",
  "body": [
    "{% alertbox ${1|exclamation,question,warning,info,success,note|} %}",
    "${2:content}",
    "{% endalertbox %}"
  ],
  "description": "Insert kiko.io's alertbox"
}

-

Alternative Blockquote

An alternative blockquote tag plugin for quotes with citator and reference url.

Files:

Syntax:

{% blockquote_alt "cite" ["citeUrl"] %}
quote
{% endblockquote_alt %}

Parameters:

No Parameter optional/default Description
1 cite Author of the quote
2 citeUrl yes Url to the quote

Usage Example:

{% blockquote_alt "Anonymous" "https://en.wikipedia.org/wiki/Lorem_ipsum" %}
Lorem ipsum dolor sit amet...
{% endblockquote_alt %}

Output:

<div>
  <blockquote>
    <p>Lorem ipsum dolor sit amet…</p>
  </blockquote>
  <cite>
    <a href="https://en.wikipedia.org/wiki/Lorem_ipsum">--- Anonymous</a>
  </cite>
</div>

Alternative Blockquote Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#blockquote_alt

VS Code Snippet:

"hexo.kiko-io.blockquote": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.blockquote",
  "body": [
    "{% blockquote_alt \"${1:cite}\" [\"${2:citeUrl}\"] %}",
    "${3:content}",
    "{% endblockquote_alt %}"
  ],
  "description": "Insert kiko.io's blockquote"
}

-

Blockquote Details

Blockquote including summary, citator and reference url, wrapped in a details tag.

Files:

Syntax:

{% blockquote_details "summary" "cite" ["citeUrl"] %}
quote
{% endblockquote_details %}

Parameters:

No Parameter optional/default Description
1 summary - Summary of the quote
2 cite - Author of the quote
3 citeUrl yes Url to the quote

quote is not a parameter, but Markdown to render.

Usage Example:

{% blockquote_details "Lorem ipsum" "Anonymous" "https://en.wikipedia.org/wiki/Lorem_ipsum" %}
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
{% endblockquote_details %}

Output:

<details>
  <summary>Lorem ipsum</summary>
  <blockquote>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
    </p>
  </blockquote>
  <cite>
    <a href="https://en.wikipedia.org/wiki/Lorem_ipsum">--- Anonymous</a>
  </cite>
</details>

Blockqoute Details Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#blockquote_details

VS Code Snippet:

"hexo.kiko-io.blockquote_details": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.blockquote_details",
  "body": [
    "{% blockquote_details \"${1:summary}\" \"${2:cite}\" [\"${3:citeUrl}\"] %}",
    "${4:quote}",
    "{% endblockquote_details %}"
  ],
  "description": "Insert kiko.io's blockquote_details"
}

-

Codepen

Embedding a pen from codepen.io.

Files:

Prequisites:

You need following configuration section in your _config.yml:

# Codepen Defaults
codepen:
  user_id: "your-name"
  default_tab: "js"
  height: 400
  width: "100%"

Syntax:

{% codepen "slugHash" "title" [defaultTab:(html,js,css)] [height] ["width"] %}

Parameters:

No Parameter optional/default Description
1 slugHash - Codepens SlugHash
2 title - Title
3 defaultTab js Default tab to show ; select out of html, js or css
4 height 300 Height as number
5 width “100%” Width as CSS value

Usage Example:

{% codepen "MWEbERg" "Lorem Ipsum" html %}

Output:

<iframe 
  height="400" 
  id="codepen-MWEbERg" 
  class="codepen" 
  src="https://codepen.io/kristofzerbe/embed/MWEbERg?height=400&amp;default-tab=html,result&amp;theme-id=light" 
  style="width: 100%;" 
  scrolling="no" 
  title="Codepen: Lorem Ipsum" 
  frameborder="no" 
  loading="lazy" 
  allowtransparency="true" 
  allowfullscreen="true">
</iframe>

Codepen Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#codepen

VS Code Snippet:

"hexo.kiko-io.codepen": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.codepen",
  "body": [
    "{% codepen \"${1:slugHash}\" \"${2:title}\" [${3|html,js,css|}] [${4:height}] [\"${5:width}\"] %}"
  ],
  "description": "Insert kiko.io's codepen"
}

-

CodeSandbox

Embedding a sandbox from CodeSandbox.

Files:

Syntax:

{% codesandbox "slugHash" "title" [height] ["width"] %}

Parameters:

No Parameter optional/default Description
1 slugHash - Sandbox’ SlugHash
2 title - Title
3 height 500 Height as number
4 width “100%” Width as CSS value

Usage Example:

{% codesandbox "cool-shamir-de613" "Lorem Ipsum" 300 %}

Output:

<iframe 
  src="https://codesandbox.io/embed/cool-shamir-de613?fontsize=14&amp;theme=light" 
  style="width:100%; height:300px; border:0; overflow:hidden;" 
  title="Lorem Ipsum" 
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
</iframe>

CodeSandbox Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#codesandbox

VS Code Snippet:

"hexo.kiko-io.codesandbox": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.codesandbox",
  "body": [
    "{% codesandbox ${1:\"slugHash}\" \"${2:title}\" [${3:height}] [\"${4:width}\"] %}"
  ],
  "description": "Insert kiko.io's codesandbox"
}

-

Button link for downloading an asset file, with additional caption (“Download <additionalCaption> <assetFile>”).

Files:

Syntax:

{% download_link "assetFile" ["additionalCaption"] %}

Parameters:

No Parameter optional/default Description
1 assetFile Asset file name to download
2 additionalCaption yes Additional caption between “Download “ and file name

Usage Example:

{% download_link "example-image_ORIGINAL.jpg" "Photo" %}

Output:

<p class="download-link">
  <a class="button" href="example-image_ORIGINAL.jpg" download="">
    Download Photo <strong>example-image_ORIGINAL.jpg</strong>
  </a>
</p>

Download Link Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#download-link

VS Code Snippet:

"hexo.kiko-io.download_link": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.download_link",
  "body": [
    "{% download_link \"${1:assetFile}\" \"${2:additionalCaption}\" %}"
  ],
  "description": "Insert kiko.io's download_link"
}

-

Github Readme

Gets the README file of a Github repo and renders its Markdown as HTML in a detail tag.

Files:

Prequisites:

You need to have installed the Axios package in your project.

The HTML output has no styles, therefore you need some in your CSS for .github-readme.

Syntax:

{% github_readme "user" "repo" ["summary"] %}

Parameters:

No Parameter optional/default Description
1 user Name of the GitHub user
2 repo Name of the GitHub repo
3 summary “Project README on Github” Caption of the DETAILS element

Usage Example:

{% github_readme "kristofzerbe" "hexo-tag-plugins" %}

Output:

<details class="github-readme">
  <summary>Project README on Github</summary>
  <div>
    <!-- Content of the README file converted to HTML -->
  </div>
</details>

Github Readme Example

VS Code Snippet:

"hexo.kiko-io.github_readme": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.github_readme",
  "body": [
    "{% github_readme \"${1:user}\" \"${2:repo}\" \"${3:[summary]}\" %}"
  ],
  "description": "Insert kiko.io's github_readme"
}

See a live example at https://kiko.io/post/GitHub-Tag-Plugins-for-Hexo/#readme

-

GitHub User & Repo Card

Renders a card-like info panel, with full information about a GitHub repo and its creator, the GitHub user.

Files:

Prequisites:

You need to have installed the Axios package in your project.

Syntax:

{% github_user_and_repo_card "user" "repo" ["cardWidth"] ["userheight"] ["avatarSize"] %}

Parameters:

No Parameter optional/default Description
1 user Name of the GitHub user
2 repo Name of the GitHub repo
3 cardWidth “400px” Maximum width of the card; Minimum is 300px
4 userheight “120px” Height of the upper user panel
5 avatarSize “90px” Size of the avatar image as CSS value

Usage Example:

{% github_user_and_repo_card "kristofzerbe" "hexo-tag-plugins" "500px" %}

Output:

<!-- see tag-github-user-and-repo-card.html -->

GitHub User & Repo Card Example

VS Code Snippet:

"hexo.kiko-io.github_user_and_repo_card": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.github_user_and_repo_card",
  "body": [
    "{% github_user_and_repo_card \"${1:user}\" \"${2:repo}\" \"${3:[cardWidth]}\" \"${4:[userhight]}\" \"${5:[avatarSize]}\" %}"
  ],
  "description": "Insert kiko.io's github_user_and_repo_card"
}

See a live example at https://kiko.io/post/GitHub-Tag-Plugins-for-Hexo/#user-and-repo-card

-

Image Compare

Comparing two asset images side-by-side with the aid of the JS library Image Compare Viewer.

Files:

Prequisites:

As this tag plugin relies on an external JS library, the files image-compare-viewer.js and image-compare-viewer.css (or its minified versions) must be loaded in the header of the web page.

Syntax:

{% image_compare 
  "imgFileOriginal" 
  "imgFileModified" 
  "descriptionModified" 
  [orientation=vertical] 
%}

Parameters:

No Parameter optional/default Description
1 imgFileOriginal - Original asset image file name
2 imgFileModified - Modified asset image file name
3 descriptionModified - Description
4 orientation null Vertical orientation Mode; set vertical to select

Usage Example:

{% image_compare 
  "example-image_ORIGINAL.jpg"
  "example-image_PRESET.jpg"
  "Lightroom Preset" 
%}

Output:

<div id="image-compare-1yrasq">
  <img class="image-compare image-original" 
       src="/post/my-post/example-image_ORIGINAL.jpg" alt="" />
  <img class="image-compare image-modified" 
       src="/post/my-post/example-image_PRESET.jpg" alt="" />
</div>
<script>
  var themeColor = "#ffffff";
  if (localStorage.getItem("theme") === 'dark') {
    themeColor = "#222222"
  }
  new ImageCompare(document.getElementById("image-compare-1yrasq"),
  {
    controlColor: themeColor,
    controlShadow: false,
    verticalMode: false,
    showLabels: true,
    labelOptions: {
      before: 'Original',
      after: 'Lightroom Preset',
      onHover: true,
    }
  }).mount();
</script>

Image Compare Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#image-compare

VS Code Snippet:

"hexo.kiko-io.image_compare": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.image_compare",
  "body": [
    "{% image_compare \"${1:imgFileOriginal}\" \"${2:imgFileModified}\" \"${3:modDesc}\" [\"${4|vertical|}\"] %}"
  ],
  "description": "Insert kiko.io's image_compare"
}

-

Renders an image including ALT attribute within a link.

Files:

Syntax:

{% image_link "assetImg" "url" "alt" %}

Parameters:

No Parameter optional/default Description
1 assetImg - Asset image file name
2 url - Url to link to
3 alt - Alternate text

Usage Example:

{% image_link "kiko-io-screenshot.png" "http://kiko.io" "Blog kiko.io" %}

Output:

<a href="http://kiko.io">
  <img src="kiko-io-screenshot.png" alt="Blog kiko.io">
</a>

VS Code Snippet:

"hexo.kiko-io.image_link": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.image_link",
  "body": [
    "{% image_link \"${1:assetImg}\" \"${2:url}\" \"${3:alt}\" %}"
  ],
  "description": "Insert kiko.io's image_link"
}

-

Image Slide

Shows multiple images within a slider with the aid of the JS library Tiny Slider.

Files:

Prequisites:

As this tag plugin relies on an external JS library, the files tiny-slider.js and tiny-slider.css (or its minified versions) must be loaded in the header of the web page.

The CSS file doesn’t include styles for the .tns-nav and its controls, but you can use the following to extend the original CSS:

.tns-nav {
    text-align: center;
    margin: 10px 0;
}
.tns-nav > [aria-controls] {
    width: 12px;
    height: 12px;
    padding: 0;
    margin: 0 5px;
    border-radius: 50%;
    background: #ddd;
    border: 0;
}
.tns-nav > .tns-nav-active {
    background: #999;
}

Syntax:

{% image_slide ..."assetImg|title" %}

Parameters:

No Parameter optional/default Description
1 ..."assetImg|title" List of pipe separated items with asset image file and title

Usage Example:

{% image_slide
  "example-image_ORIGINAL.jpg|Original"
  "example-image_PRESET.jpg|Lightroom Preset"
%}

Output:

<div class="image-slider" id="image-slide-w7jgxk">
  <div>
    <img src="/post/my-post/example-image_ORIGINAL.jpg" alt="Original" />
  </div>
  <div>
    <img src="/post/my-post/example-image_PRESET.jpg" alt="Lightroom Preset" />
  </div>
</div>
<script>
  tns({
    container: "#image-slide-w7jgxk",
    items: 1,
    slideBy: "page",
    controls: false,
    nav: true
  });
</script>

Image Slide Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#image-slide

VS Code Snippet:

"hexo.kiko-io.image_slide": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.image_slide",
  "body": [
    "{% image_slide ${1:...\"assetImg|title\"} %}"
  ],
  "description": "Insert kiko.io's image_slide"
}

-

Indiepen

Embedding a “local” pen (index.html, main.js and styles.css stored in an asset subfolder) via Indiepen.

Files:

Prequisites:

You need following configuration section in your _config.yml:

# Indiepen Defaults
indiepen:
  default_tab: "result"
  height: 450

Syntax:

{% indiepen "subfolder" [height] [defaultTab:(result,html,css,js)] %}

Parameters:

No Parameter optional/default Description
1 subfolder Asset subfolder with indiepen files
2 defaultTab result Default tab to show ; select out of result, html, js or css
3 height 450 Height as number

Usage Example:

{% indiepen "my-pen" 300 html %}

Output:

<iframe class="indiepen"
        src="https://indiepen.tech/embed/?url=https%3A%2F%2Fmy-blog.com%2Fpost%2Fmy-post%2Fmy-pen&tab=html"
        style="width: 100%; overflow: hidden; display: block; border: 0;"
        title="Indiepen Embed"
        loading="lazy" 
        width="100%" 
        height="300">
</iframe>

Indiepen Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#indiepen

VS Code Snippet:

"hexo.kiko-io.indiepen": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.indiepen",
  "body": [
    "{% indiepen \"${1:subfolder}\" ${2:height} ${3|result,html,css,js|} %}"
  ],
  "description": "Insert kiko.io's indiepen"
}

-

More Info

Renders a list of related, informative links regarding a post.

Files:

Syntax:

{% moreinfo '{ "list": [
  [ "publisher", "title", "url" ]
]}' %}

Usage Example:

{% moreinfo '{ "list": [
  [ "Wikipedia", "Markdown",
  "https://en.wikipedia.org/wiki/Markdown" ],
  [ "Markdown Guide", "Basic Syntax",
  "https://www.markdownguide.org/basic-syntax/" ],
  [ "Daring Fireball", "Markdown: Syntax",
  "https://daringfireball.net/projects/markdown/syntax" ]
]}' %}

Output:

<ul class="moreinfo-list">
  <li>Wikipedia: <a href="https://en.wikipedia.org/wiki/Markdown">Markdown</a></li>
  <li>Markdown Guide: <a href="https://www.markdownguide.org/basic-syntax/">Basic Syntax</a></li>
  <li>Daring Fireball: <a href="https://daringfireball.net/projects/markdown/syntax">Markdown: Syntax</a></li>
</ul>

More Info Example

See a live example at https://kiko.io/post/Hexo-Tag-Plugin-Collection/#more-info

VS Code Snippet:

"hexo.kiko-io.moreinfo": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.moreinfo",
  "body": [
    "{% moreinfo '{ \"list\": [",
    "  [ ${1:\"publisher\"}, ${2:\"title\"},",
    "  ${3:\"url\"} ]$0",
    "]}' %}"
  ],
  "description": "Insert kiko.io's moreinfo"
}

To insert one more item to the list, use:

"hexo.kiko-io.moreinfo.item": {
  "scope": "markdown",
  "prefix": "hexo.kiko-io.moreinfo.item",
  "body": [
    "[ ${1:\"publisher\"}, ${2:\"title\"},", 
    "${3:\"url\"} ]$0"
  ],
  "description": "Insert kiko.io's moreinfo item"
}

-

History

2021-12-29

  • Description of parameters added
  • Github Readme added
  • GitHub User & Repo Card added

2021-12-12

  • Initial Commit

License

MIT : http://opensource.org/licenses/MIT

See https://github.com/kristofzerbe/hexo-tag-plugins#github-readme for more details.


GitHub User & Repo Card

Renders a card-like info panel, with full information about a GitHub repo and its creator, the GitHub user.

Usage Example:

1
{% github_user_and_repo_card "kristofzerbe" "hexo-tag-plugins" "500px" %}

Live Output:

26 Repos
7 Followers
0 1
0 0

hexo-tag-plugins

Hexo Tag Plugin Collection from kiko.io

  • JavaScript64.2%
  • HTML18.6%
  • CSS17.1%

MIT License

See https://github.com/kristofzerbe/hexo-tag-plugins#github-user–repo-card for more details.

Webmentions

No Webmentions yet...

In case your blog software can't send Webmentions, you can use this form to submit me a mention of this article...


Comments

Related