Project

jekyll-ham

0.0
The project is in a healthy, maintained state
Hackapedia's Abstraction Machine.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Runtime

~> 3.7
~> 3.26, >= 3.26.1
~> 4.2
~> 2.7, >= 2.7.1
 Project Readme
layout title further_reading external_links
page
Main Page
title url target
Official Documentation
_blank
title url icon target
Ruby Gem (Package)
bi bi-gem
_blank
title url icon target
Release History
bi bi-clock-history
_blank
title url icon target
GitHub Repository
bi bi-github
_blank
title url icon target
Issues List
bi bi-bug
_blank
title url icon target
Discussions
bi bi-chat-dots
_blank

HAM 🥩

HAM is a Jekyll-based boilerplate template for generating better, static wiki-style websites. HAM can be instantly used to build static wiki pages. But the best of all, the default theme of HAM can be easily customized to create more personalized wiki pages, unlike those from MediaWiki, for example.

This project is built to replace the current, MediaWiki installation at <hackapedia.reinhart1010.id> after I found out difficult to create custom styles for it, while other, Git-based alternatives such as GitHub Wiki sucks (no, really) and may not support self-hosting on shared hosting providers.

What does HAM stand for?

HAM is short for:

  • Hackapedia's Abstraction Machine
  • HAM Ain't MediaWiki
  • Halfmoon and Markdown
  • && i++ (can we get more pull requests to add more stuff into this list?)

Features

What HAM is

  • A static-site wiki generator
  • A better alternative than GitHub pages
  • Highly customizable through Halfmoon and Jekyll
  • Uses GitHub-Flavored Markdown (GFM)
  • Optimized for GitHub Pages and Gitlab Pages

What HAM isn't

  • Optimized for large wiki content (this is where advanced alternatives such as MediaWiki excels at)
  • Built-in support for hosting content written in MediaWiki markup syntax (however there are converters to Markdown)
  • Supported in legacy web browsers (see Compatibility)

What HAM would be

  • Supporting Forem (DEV.to) liquid tags (YouTube embeds, Twitter posts, etc.)

Usage

You don't need to clone this project to use HAM on your own wiki. It's available as a Gem-based theme on the official Ruby gems repository. If you are unsure on installing gem-based themes like this one, check out the official Jekyll documentation for that.

If you have just created a new site with jekyll new <PATH> chances are that you're using the default, Minima theme instead of HAM. If that's the case, replace the line which begins with

gem "minima"

on your Gemfile with

gem "jekyll-ham", "~> 0.1.2"

Also don't forget to change the theme configuration on your _config.yml to jekyll-ham instead of minima.

Site does not load properly after first jekyll build?

Make sure that all of your Markdown and HTML files include the following frontmatter:

---
layout: page
---

This ensures that the default page template (as defined in our _layouts/page.html) is used to load the entire content

Changing the _config.yml

HAM also introduces additional configuration which you can set on your _config.yml:

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
  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.
      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

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.

Credits & Open Source Licenses

Copyright (c) 2021 Reinhart Previano Koentjoro.

This project is distributed under MIT License, and also uses the following open-source components: