1
\$\begingroup\$

The source code of this project aims to enable defining contact information either via FrontMatter or named parameters, and having that information then formatted to HTML that is both human and machine readable. I've attempted to adhere to the MicroCode specifications for both HCard and VCard formats, and allow for easy customization, but I believe there's always room for improvement.


Questions

  • Have I made any mistakes or deviated too far from the MicroCode format(s)?

  • Are there any features that should be added?

  • Any suggestions for making Liquid code easier to extend?


Requirements

The source code and setup instructions are intended for those utilizing Jekyll built sites on GitHub Pages. The Jekyll site has documentation regarding GitHub Pages, and GitHub has further documentation regarding Jekyll.


Setup

The ReadMe file contains more detailed instructions for setup, but the TLDR is as follows.

  • Change current working directory to a repository utilizing Jekyll to build static web pages...
cd ~/git/hub/<name>/<repo>
  • Check-out the gh-pages branch and make directory path for including modules...
git checkout gh-pages

mkdir -p _includes/modules
  • Add this project as a Git Submodule
git submodule add -b 'main'\
  --branch 'includes-hcard'\
  'https://github.com/liquid-utilities/includes-hcard.git'\
  '_includes/modules/includes-hcard'

Notice, for GitHub Pages one must use the https URL for Git Submodules

  • Add an include statement to your site's default layout, eg...

_layouts/default.html

---
license: MIT
source: https://raw.githubusercontent.com/jekyll/minima/v2.0.0/_layouts/default.html
---
<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

  {% include head.html %}

  <body>

    {% include header.html %}

    <main class="page-content" aria-label="Content">
      <div class="wrapper">
        {{ content }}

        {% if page.hcard %}
          <div class="contacts">
            {% include modules/includes-hcard/hcard.html %}
          </div>
        {% endif %}
      </div>
    </main>

    {% include footer.html %}

  </body>

</html>
  • Commit added Git Submodule and theme modifications...
git commit -F- <<'EOF'
:heavy_plus_sign: Adds `liquid-utilities/includes-hcard#1` submodule



**Adds**


- `.gitmodules`, tracks submodules AKA Git within Git _fanciness_

- `_modules_/includes-hcard`, Builds HCard compatible with VCard HTML format

- `_layouts/default.html`, modified default layout from `jekyll/minima` theme
EOF

Usage

  • Use FrontMatter configurations for the selected layout...

_posts/2020-07-05-frontmatter-hcard.md

---
layout: post
date: 2020-07-05 10:44:25 -0700
title: FrontMatter HCard
excerpt: Example of using FrontMatter to define HCard content

hcard:
  organization: Distribution
  name: Jayne Cobb

  # email_type: office
  # email_address: name@example.com
  emails:
    - type: office
      address: name@example.com

  # phone_type: cell
  # phone_number: 555-123-4567
  phone_numbers:
    - type: cell
      number: 555-123-4567

    - type: office
      number: 555-987-6543

  address:
    street: 418 Code St.
    extended: Suite 503       ## AKA suite, apartment, etc.
    country_code: USA
    country_name: United States of America
    locality: Server Request  ## AKA city
    region: ZZ                ## AKA state
    postal_code: 12345        ## AKA zip

  # link_label: 'example'
  # link_url: https://example.com
  links:
    - label: 'example one'
      url: https://example.com

    - label: 'example two'
      url: https://example.com

    - label: 'example three'
      url: https://example.com
---

A live example of output above is hosted thanks to GitHub Pages, the resulting HTML for above configurations is similar to...

includes-hcard/2020/07/05/frontmatter-hcard.html (snip)

<div id="hcard-jayne-cobb" class="h-card vcard">
  <div class="p-org org">Distribution</div>
  <div class="p-name fn">Jayne Cobb</div>

  <div class="p-tel tel">
    <span class="type">cell</span>:
    <a class="value">555-123-4567</a>
  </div>

  <div class="p-tel tel">
    <span class="type">office</span>:
    <a class="value">555-987-6543</a>
  </div>

  <div class="u-email email">
    <span class="type">office</span>:
    <a class="value" href="mailto:name@example.com">name@example.com</a>
  </div>

  <div class="p-adr adr">
    <span class="p-street-address street-address">418 Code St.</span>
    <span class="p-locality locality">Server Request</span>, <span class="p-region region">ZZ</span>
    <span class="p-postal-code postal-code">12345</span>
    <span class="p-country-name usa" title="United States of America">USA</span>
  </div>

  <div><a class="url fn org" href="https://example.com">example one</a>: <small>https://example.com</small></div>
  <div><a class="url fn org" href="https://example.com">example two</a>: <small>https://example.com</small></div>
  <div><a class="url fn org" href="https://example.com">example three</a>: <small>https://example.com</small></div>
</div>
  • Or use include directly and assign via named parameters...

_posts/2020-07-05-includes-hcard.md

---
layout: post
date: 2020-07-05 10:44:25 -0700
title: Includes HCard
excerpt: Example of using `include` keyword to define HCard content
---



This post is a _live_ example of using `include` keyword to define HCard content, [source code][post__includes_hcard__source] is available on GitHub.



{% include modules/includes-hcard/hcard.html name='Jayne Cobb'
                                             organization='Distribution'
                                             phone_type='cell'
                                             phone_number='555-123-4567'
                                             email_type='office'
                                             email_address='name@example.com'
                                             address_street='418 Code St.'
                                             address_extended='Suite 503'
                                             address_locality='Server Request'
                                             address_postal_code='12345'
                                             address_region='ZZ'
                                             address_country_code='USA'
                                             address_country_name='United States of America'
                                             link_label='Web Site'
                                             link_url='https://example.com' %}



[post__includes_hcard__source]: https://github.com/liquid-utilities/includes-hcard/blob/gh-pages/_posts/2020-07-05-includes-hcard.md

Again a live example of output above is hosted on GitHub Pages, the resulting HTML for above configurations is similar to...

includes-hcard/2020/07/05/includes-hcard.html (snip)

<div id="hcard-jayne-cobb" class="h-card vcard">
  <div class="p-org org">Distribution</div>
  <div class="p-name fn">Jayne Cobb</div>
  <span class="type">cell</span>: <a class="p-tel tel">555-123-4567</a>

  <div class="u-email email">
    <span class="type">office</span>:
    <a class="value" href="mailto:name@example.com">name@example.com</a>
  </div>

  <div class="p-adr adr">
    <span class="p-street-address street-address">418 Code St.</span>
    <span class="p-locality locality">Server Request</span>, <span class="p-region region">ZZ</span>
    <span class="p-postal-code postal-code">12345</span>
    <span class="p-country-name usa" title="United States of America">USA</span>
  </div>

  <div><a class="url fn org" href="https://example.com">Web Site</a>: <small>https://example.com</small></div>
</div>
  • Commit changes and push to GitHub...
git add _posts/2020-07-05-frontmatter-hcard.md
git commit -m ':memo: Adds post FrontMatter HCard'

git add _posts/2020-07-05-includes-hcard.md
git commit -m ':memo: Adds post Includes HCard'

git push origin gh-pages

Source Code

hcard.html

{% capture workspace__hcard %}
{% comment %}
---
version: 0.0.1
license: AGPL-3.0
author: S0AndS0
---
{% endcomment %}


{% assign name = include.hame | default: page.hcard.name | default: nil %}
{% assign organization = include.organization | default: page.hcard.organization | default: nil %}

{% assign photo_alt = include.photo_alt | default: page.hcard.photo.alt | default: nil %}
{% assign photo_src = include.photo_src | default: page.hcard.photo.src | default: nil %}
{% unless photo_alt %}
  {% if photo_src and name %}
    {% assign photo_alt = "Photo of " | append: name %}
  {% elsif photo_src and organization %}
    {% assign photo_alt = "Photo of " | append: organization %}
  {% endif %}
{% endunless %}

{% assign email_address = include.email_address | default: page.hcard.email_address | default: nil %}
{% assign email_type = include.email_type | default: page.hcard.email_type | default: nil %}
{% assign emails = include.emails | default: page.hcard.emails | default: nil %}

{% assign phone_type = include.phone_type | default: page.hcard.phone_type | default: nil %}
{% assign phone_number = include.phone_number | default: page.hcard.phone_number | default: nil %}
{% assign phone_numbers = include.phone_numbers | default: page.hcard.phone_numbers | default: nil %}

{% assign address_street = include.address_street | default: page.hcard.address.street | default: nil %}
{% assign address_extended = include.address_extended | default: page.hcard.address.extended | default: nil %}
{% assign address_country_code = include.address_country_code | default: page.hcard.address.country_code | default: nil %}
{% assign address_country_name = include.address_country_name | default: page.hcard.address.country_name | default: nil %}
{% assign address_locality = include.address_locality | default: page.hcard.address.locality | default: nil %}
{% assign address_region = include.address_region | default: page.hcard.address.region | default: nil %}
{% assign postal_code = include.address_postal_code | default: page.hcard.address.postal_code | default: nil %}

{% assign links = include.links | default: page.hcard.links | default: nil %}
{% assign link_label = include.link_label | default: page.hcard.link_label | default: nil %}
{% assign link_url = include.link_url | default: page.hcard.link_url | default: nil %}


{% if organization or name %}
  {% if name %}
    <div id="hcard-{{ name | downcase | replace: ' ','-' }}" class="h-card vcard">
  {% elsif organization %}
    <div id="hcard-{{ organization | downcase | replace: ' ','-' }}" class="h-card vcard">
  {% endif %}

      {% if photo_src and photo_alt %}
        <img class="photo" src="{{ photo_src }}" alt="{{ photo_alt }}">
      {% endif %}

      {% if organization %}
        <div class="p-org org">{{ organization }}</div>
      {% endif %}

      {% if name %}
        <div class="p-name fn">{{ name }}</div>
      {% endif %}

      {% if phone_numbers %}
        {% for phone in phone_numbers %}
          <div class="p-tel tel">
          {% if phone.type %}<span class="type">{{ phone.type }}</span>: {% endif %}
            <a class="value">{{ phone.number }}</a>
          </div>
        {% endfor %}
      {% elsif phone_number %}
        {% if phone_type %}<span class="type">{{ phone_type }}</span>: {% endif %}
        <a class="p-tel tel">{{ phone_number }}</a>
      {% endif %}

      {% if emails %}
        {% for email in emails %}
          <div class="u-email email">
            {% if email.type %}
              <span class="type">{{ email.type }}</span>:
            {% endif %}
            <a class="value" href="mailto:{{ email.address }}">{{ email.address }}</a>
          </div>
        {% endfor %}
      {% elsif email_address %}
        <div class="u-email email">
          {% if email_type %}<span class="type">{{ email_type }}</span>: {% endif %}
          <a class="value" href="mailto:{{ email_address }}">{{ email_address }}</a>
        </div>
      {% endif %}

      {% if address_street or extended_address or address_locality or address_region or postal_code or address_country_code or address_country_name %}
        <div class="p-adr adr">
          {% if address_street %}
            <span class="p-street-address street-address">{{ address_street }}</span>
          {% endif %}
          {% if extended_address %},
            <span class="p-extended-address extended-address">{{ extended_address }}</span>
          {% endif %}
          {% if address_locality %}
            <span class="p-locality locality">{{ address_locality }}</span>
          {% endif %}
          {% if address_region %},
            <span class="p-region region">{{ address_region }}</span>
          {% endif %}
          {% if postal_code %}
            <span class="p-postal-code postal-code">{{ postal_code }}</span>
          {% endif %}
          {% if address_country_code %}
            <span class="p-country-name {{ address_country_code | downcase }}"{% if address_country_name %} title="{{ address_country_name }}"{% endif %}>
              {{ address_country_code }}
            </span>
          {% endif %}
        </div>
      {% endif %}

      {% if links %}
        {% for link in links %}
          <div><a class="url fn org" href="{{ link.url }}">{{ link.label }}</a>: <small>{{ link.url }}</small></div>
        {% endfor %}
      {% elsif link_label and link_url %}
        <div><a class="url fn org" href="{{ link_url }}">{{ link_label }}</a>: <small>{{ link_url }}</small></div>
      {% endif %}

  </div>
{% endif %}

{% endcapture %}{%- if workspace__hcard -%}{{ workspace__hcard | strip }}{% assign workspace__hcard = nil %}{%- endif -%}
\$\endgroup\$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.