feat: Publish new version

reinhart1010 · May 31, 2023 · 29798c4 · 29798c4
1 parent 50be8ac
commit 29798c4
Show file tree

Hide file tree

Showing 10 changed files with 165 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -97,21 +97,110 @@ layout: page
 
 However, as of 0.1.6 `jekyll-optional-front-matter` has been included and configured by default to remove this requirement, which allows easier content migration for future wikis.
 
-### Changing the `_config.yml`
+## Configuration
 HAM also introduces additional configuration which you can set on your `_config.yml`:
 
+### Site Identity
 ```yaml
 ham:
  site_icon: https://raw.githubusercontent.com/googlefonts/noto-emoji/main/svg/emoji_u1f969.svg # Your site icon, to be displayed on navbar
  site_favicon: null # Your site favicon, in case you have a spare favicon.ico for it
+ site_meta:
+ - name: google-site-verification
+ content: AAAAAA
+ - name: msvalidate.01
+ content: BBBBBB
  contributing: # Additional metadata for "Contribute to This Page" section on sidebar
  discuss: # For "Discuss" (or "Talk page" on MediaWiki)
- type: url # Currently supports "url". Support for other discussion widgets such as DiscussBot (Telegram), Disqus, and Utteranc.es are coming soon.
+ type: url | custom | facebook | giscus | telegram | utterances
  url: https://github.com/reinhart1010/HAM/discussions/
  view_source_base_url: https://github.com/reinhart1010/HAM/blob/main/ # The base URL to publicly view the original (Markdown) source code
  issue_url: https://github.com/reinhart1010/HAM/issues/ # The URL to report an issue related to site or content
 ```
 
+### Comments
+HAM provides built-in support for Facebook, Giscus, Telegram, and Utteranc.es widgets plugins. However, you can also add your own widgets or links by following these instructions.
+
+#### URL (Default)
+If you have a dedicated forum or discussion webpage, such as GitHub Discussions, you can link them directly to all HAM pages by setting Jekyll's `_config.yml` as below.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: url
+ url: https://github.com/reinhart1010/HAM/discussions/
+```
+
+#### Custom Comments Widget (HTML code)
+You can use an custom-made comments widget (e.g. JavaScript-based or `<iframe>` element) into HAM by placing the code under `_includes/custom-comments.html`. You can also use Jekyll-specific variables and attributes including `{{ site.url }}` to render custom widget code.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: custom
+```
+
+#### Facebook
+HAM includes an external JavaScript from Facebook in order to render the Facebook Comments Widget. You are also required to register your website as an app on Facebook, [switch from Development Mode to Live/Public Mode](https://developers.facebook.com/docs/development/build-and-test/app-modes), and insert your App ID and preferred language into the configuration below.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: facebook
+ app_id: 123456789
+ lang: en_US
+```
+
+#### Giscus
+[Giscus](https://giscus.app) is yet another comment widget plugin powered by GitHub Discussions. To set up Giscus for HAM, [follow their installation instructions](https://giscus.app), and modify the `_config.yml` according to the values obtained from the generated HTML snippet.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: utterances
+ repo: data-repo
+ repo_id: data-repo-id
+ category: data-category
+ category_id: data-category-id
+ mapping: data-mapping
+ reactions_enabled: data-reactions-enabled
+ emit_metadata: data-emit-metadata
+ theme: data-theme # "preferred_color_scheme" is preferred to allow HAM's dark mode integration to work smoothly
+ lang: data-lang
+```
+
+#### Telegram (@DiscussBot)
+HAM supports for Telegram's [@DiscussBot](https://t.me/DiscussBot) web comments widget. **This widget may not sync with comments on Telegram channels set up via [discussion groups](https://telegram.org/blog/privacy-discussions-web-bots).**
+
+To set up the widget, follow the instructions provided on https://comments.app under your Telegram account, and modify the `_config.yml` according to the values obtained from the generated HTML snippet.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: telegram
+ telegram_discussion: data-telegram-discussion
+```
+
+#### Utterances
+> **DEPRECATED:** The value `utteranc.es` has been deprecated, removed, and replaced with `utterances` (without the dot).
+
+[Utterances](https://utteranc.es) is yet another comment widget plugin powered by GitHub Issues. To set up Utterances for HAM, [follow their installation instructions](https://utteranc.es), and modify the `_config.yml` according to the values obtained from the generated HTML snippet.
+
+```yaml
+ham:
+ contributing:
+ discuss:
+ type: utterances
+ repo: data-repo
+ issue_term: issue_term # optional
+ theme: theme # "preferred-color-scheme" is preferred to allow HAM's dark mode integration to work smoothly
+```
+
 ## Browser Compatibility
 HAM heavily uses [Halfmoon] CSS framework on the generated page due to its theming flexibility based on CSS variables. However, that comes with a cost: **CSS variables are not supported in old browsers**. If you're thinking of Internet Explorer 11, well, don't think too far, because this exact feature may not be supported on some smart TV models, too! There are plans to either include a JavaScript-based polyfill or fallback CSS for this, but I might want to do that later.
 

diff --git a/_includes/comments.html b/_includes/comments.html
@@ -1,21 +1,48 @@
-{% if site.ham.contributing != null %}
- {% if site.ham.contributing != null %}
- {% if site.ham.contributing.discuss.type != null && site.ham.contributing.discuss.type != 'url' %}
- <h5 id="discuss" class="sidebar-title">Discuss this page</h5>
- <div class="sidebar-title">
+{% if page.contributing != null || site.ham.contributing != null %}
+ {% if page.contributing.discuss.type != 'url' || site.ham.contributing.discuss.type != 'url' %}
+ <h5 id="discuss" class="sidebar-title">Discuss this page</h5>
+ <div class="sidebar-title">
+ {% if page.contributing.discuss.type != null %}
+ {% case page.contributing.discuss.type %}
+ {% when 'custom' %}
+ {% include custom-comments.html %}
+ {% when 'facebook' %}
+ {% if page.contributing.discuss.label != null %}
+ <div id="fb-root"></div>
+ <script async defer crossorigin="anonymous" src="https://connect.facebook.net/{{ page.contributing.discuss.lang }}/sdk.js#xfbml=1&version=v17.0&appId={{ page.contributing.discuss.app_id }}&autoLogAppEvents=1" nonce="mqsBinib"></script>
+ <div class="fb-comments" data-href="https://developers.facebook.com/docs/plugins/comments#configurator" data-width="" data-numposts="5"></div>
+ {% when 'giscus' %}
+ <script src="https://giscus.app/client.js" data-repo="{{ page.contributing.discuss.repo }}" data-repo-id="{{ page.contributing.discuss.repo_id }}" data-category="{{ page.contributing.discuss.category }}" data-category-id="{{ page.contributing.discuss.category_id }}" data-mapping="{{ page.contributing.discuss.mapping }}" data-reactions-enabled="{{ page.contributing.discuss.reactions_enabled | default: 1 }}" data-emit-metadata="{{ page.contributing.discuss.emit_metadata | default: 0 }}" data-theme="{{ page.contributing.discuss.theme | default: 'preferred_color_scheme' }}" data-lang="{{ page.contributing.discuss.lang | default: 'en' }}" crossorigin="anonymous" async></script>
+ {% when 'telegram' %}
+ <script src="https://telegram.org/js/telegram-widget.js?15" {% if page.contributing.discuss.telegram_discussion != null %} data-telegram-discussion="{{ page.contributing.discuss.telegram_discussion }}" {% endif %} data-comments-limit="{{ page.contributing.discuss.comments_limit | default: '5' }}" {% if page.contributing.discuss.height != null %} data-height="{{ page.contributing.discuss.height }}" {% endif %} data-color="{{ page.contributing.discuss.color | default: '319BE6' }}" data-dark-color="{{ page.contributing.discuss.color | default: '4BA3E2' }}" data-colorful="{{ page.contributing.discuss.colorful | default: 0 }}" data-dark="{{ page.contributing.discuss.dark | default: 0 }}" crossorigin="anonymous" async></script>
+ {% when 'utterances' %}
+ <script src="https://utteranc.es/client.js" repo="{{ page.contributing.discuss.repo }}" issue-term="{{ page.contributing.discuss.issue_term }}"
+ {% if page.contributing.discuss.label != null %}
+ label="{{ page.contributing.discuss.label }}"
+ {% endif %}
+ theme="{{ page.contributing.discuss.theme | default: 'preferred-color-scheme' }}" crossorigin="anonymous" async></script>
+ {% endcase %}
+ {% else %}
  {% case site.ham.contributing.discuss.type %}
+ {% when 'custom' %}
+ {% include custom-comments.html %}
+ {% when 'facebook' %}
+ {% if site.ham.contributing.discuss.label != null %}
+ <div id="fb-root"></div>
+ <script async defer crossorigin="anonymous" src="https://connect.facebook.net/{{ site.ham.contributing.discuss.lang }}/sdk.js#xfbml=1&version=v17.0&appId={{ site.ham.contributing.discuss.app_id }}&autoLogAppEvents=1" nonce="mqsBinib"></script>
+ <div class="fb-comments" data-href="https://developers.facebook.com/docs/plugins/comments#configurator" data-width="" data-numposts="5"></div>
  {% when 'giscus' %}
  <script src="https://giscus.app/client.js" data-repo="{{ site.ham.contributing.discuss.repo }}" data-repo-id="{{ site.ham.contributing.discuss.repo_id }}" data-category="{{ site.ham.contributing.discuss.category }}" data-category-id="{{ site.ham.contributing.discuss.category_id }}" data-mapping="{{ site.ham.contributing.discuss.mapping }}" data-reactions-enabled="{{ site.ham.contributing.discuss.reactions_enabled | default: 1 }}" data-emit-metadata="{{ site.ham.contributing.discuss.emit_metadata | default: 0 }}" data-theme="{{ site.ham.contributing.discuss.theme | default: 'preferred_color_scheme' }}" data-lang="{{ site.ham.contributing.discuss.lang | default: 'en' }}" crossorigin="anonymous" async></script>
  {% when 'telegram' %}
  <script src="https://telegram.org/js/telegram-widget.js?15" {% if site.ham.contributing.discuss.telegram_discussion != null %} data-telegram-discussion="{{ site.ham.contributing.discuss.telegram_discussion }}" {% endif %} data-comments-limit="{{ site.ham.contributing.discuss.comments_limit | default: '5' }}" {% if site.ham.contributing.discuss.height != null %} data-height="{{ site.ham.contributing.discuss.height }}" {% endif %} data-color="{{ site.ham.contributing.discuss.color | default: '319BE6' }}" data-dark-color="{{ site.ham.contributing.discuss.color | default: '4BA3E2' }}" data-colorful="{{ site.ham.contributing.discuss.colorful | default: 0 }}" data-dark="{{ site.ham.contributing.discuss.dark | default: 0 }}" crossorigin="anonymous" async></script>
- {% when 'utteranc.es' %}
+ {% when 'utterances' %}
  <script src="https://utteranc.es/client.js" repo="{{ site.ham.contributing.discuss.repo }}" issue-term="{{ site.ham.contributing.discuss.issue_term }}"
  {% if site.ham.contributing.discuss.label != null %}
  label="{{ site.ham.contributing.discuss.label }}"
  {% endif %}
- theme="{{ site.ham.contributing.discuss.theme | default: 'preferred-color-scheme' }}" crossorigin="anonymous" async></script>
+  theme="{{ site.ham.contributing.discuss.theme | default: 'preferred-color-scheme' }}" crossorigin="anonymous" async></script>
  {% endcase %}
- </div>
- {% endif %}
+ {% endif %}
+ </div>
  {% endif %}
-{% endif %}
+{% endif %}
diff --git a/_includes/custom-comments.html b/_includes/custom-comments.html
@@ -0,0 +1,4 @@
+<div class="alert alert-danger" role="alert">
+ <h4 class="alert-heading">Error: Custom comment widget is not set up.</h4>
+ Make sure that the custom comment widget code is placed under <code>/_includes/custom-comments.html</code>, then recompile.
+</div>
diff --git a/_includes/search-modal.html b/_includes/search-modal.html
@@ -9,4 +9,4 @@
  <span>Search articles on this site...</span>
  </div>
  </div>
-</div>
+</div>
diff --git a/_includes/sidebar.html b/_includes/sidebar.html
@@ -4,27 +4,38 @@ <h5 id="on-this-page" class="sidebar-title">On This Page</h5>
  <div class="sidebar-divider"></div>
  <div id="_ham_on_this_page_ul"></div>
  <br>
- {% if site.ham.contributing != null %}
+ {% if page.contributing != null || site.ham.contributing != null %}
  <h5 id="contribute" class="sidebar-title">Contribute to This Page</h5>
  <div class="sidebar-divider"></div>
- {% if site.ham.contributing.discuss.type != null %}
- <a href="{% if site.ham.contributing.discuss.type == 'url' %}{{ site.ham.contributing.discuss.url }}{% else %}#discuss{% endif %}" class="sidebar-link sidebar-link-with-icon">
+ {% if page.contributing.discuss.type != null || site.ham.contributing.discuss.type != null %}
+ <a 
+ {% if page.contributing.discuss.type == 'url' || site.ham.contributing.discuss.type == 'url' %}
+ href="{{ page.contributing.discuss.url | default: site.ham.contributing.discuss.url }}"
+ {% else %}
+ #discuss
+ {% endif %} class="sidebar-link sidebar-link-with-icon">
  <span class="sidebar-icon">
  <i class="bi bi-chat-dots" aria-hidden="true"></i>
  </span>
  Discuss
  </a>
  {% endif %}
- {% if site.ham.contributing.issue_url != null %}
- <a href="{{ site.ham.contributing.issue_url }}" class="sidebar-link sidebar-link-with-icon">
+ {% if page.contributing.issue_url != null || site.ham.contributing.issue_url != null %}
+ <a href="{{ page.contributing.issue_url | default: site.ham.contributing.issue_url }}" class="sidebar-link sidebar-link-with-icon">
  <span class="sidebar-icon">
  <i class="bi bi-bug" aria-hidden="true"></i>
  </span>
  Report New Issue
  </a>
  {% endif %}
- {% if site.ham.contributing.view_source_base_url != null %}
- <a href="{{ site.ham.contributing.view_source_base_url }}{{ page.path }}" class="sidebar-link sidebar-link-with-icon">
+ {% if page.contributing.view_source_url != null || site.ham.contributing.view_source_base_url != null %}
+ <a
+ {% if page.contributing.issue_url != null %}
+ href="{{ page.contributing.view_source_url }}"
+ {% else %}
+ href="{{ site.ham.contributing.view_source_base_url }}{{ page.path }}"
+ {% endif %}
+ class="sidebar-link sidebar-link-with-icon">
  <span class="sidebar-icon">
  <i class="bi bi-code-slash" aria-hidden="true"></i>
  </span>

diff --git a/_layouts/default.html b/_layouts/default.html
@@ -4,8 +4,10 @@
  <!-- Meta tags -->
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
- <meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport" />
  <meta name="viewport" content="width=device-width" />
+ {% for meta in site.ham.site_meta %}
+ <meta name="{{ meta.name }}" content="{{ meta.content }}" />
+ {% endfor %}
 
  <!-- Favicon and title -->
  <link rel="icon" href="{{ site.ham.site_favicon | default: site.ham.site_icon }}">
@@ -24,6 +26,10 @@
  <link href="{{ site.url }}/assets/main.css" rel="stylesheet" />
  <link href="{{ site.url }}/assets/syntax-highlighter.css" rel="stylesheet" />
 
+ <!-- rel-me Links -->
+ {% for link in site.ham.site_rel_me %}
+ <link href="{{ link }}" rel="me" />
+ {% endfor %}
 </head>
 <body class="with-custom-webkit-scrollbars with-custom-css-scrollbars" data-dm-shortcut-enabled="true" data-sidebar-shortcut-enabled="true" data-set-preferred-mode-onload="true">
  {% include search-modal.html %}

diff --git a/assets/bootstrap-icons.min.css b/assets/bootstrap-icons.min.css
diff --git a/assets/fonts/bootstrap-icons.woff b/assets/fonts/bootstrap-icons.woff
diff --git a/assets/fonts/bootstrap-icons.woff2 b/assets/fonts/bootstrap-icons.woff2
diff --git a/jekyll-ham.gemspec b/jekyll-ham.gemspec
@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
  spec.name = "jekyll-ham"
- spec.version = "0.2.3"
+ spec.version = "0.3.0"
  spec.authors = ["Reinhart Previano Koentjoro"]
  spec.email = ["[email protected]"]