How Can You Embed and Manage Code with GitHub Gist in a Multilingual Jekyll Site
Why Use GitHub Gist with Jekyll?
Managing code snippets inside Markdown files can become messy and redundant across language versions. GitHub Gist helps you:
- Centralize code examples outside the Jekyll repo
- Reuse the same snippet across multiple pages or languages
- Update code examples without rebuilding your site
- Enable external contributors to suggest improvements
Step 1: Create a GitHub Gist
Buka https://gist.github.com, lalu buat Gist baru. Simpan file dengan nama sesuai bahasa, misalnya:
config-example-en.rbconfig-example-id.rb
https://gist.github.com/username/123456abcdef7890
Maka ID-nya adalah 123456abcdef7890.
Step 2: Tambahkan ID Gist ke Data File
Buat file:_data/gists.yml
configuration:
en: 123456abcdef7890
id: abcdef1234567890
Key `configuration` disesuaikan dengan `nav_key` halaman.
Step 3: Buat Include untuk Menampilkan Gist
Buat file:_includes/gist-snippet.html
{% assign key = page.nav_key %}
{% assign lang = page.lang | default: "en" %}
{% assign gist_id = site.data.gists[key][lang] %}
{% if gist_id %}
<script src="https://gist.github.com/{{ gist_id }}.js"></script>
{% else %}
<div class="notice warning">No code snippet available for this language.</div>
{% endif %}
Step 4: Tambahkan ke Layout atau Halaman
Di dalam halaman dokumentasi atau layout (misalnyadocs.html), masukkan:
{% raw %}{% include gist-snippet.html %}{% endraw %}
Bonus: Tambahkan Tombol Edit Gist
Jika user ingin menyumbang perubahan:{% if gist_id %}
<a href="https://gist.github.com/{{ gist_id }}" target="_blank">View or Edit Gist on GitHub</a>
{% endif %}
Use Case: Language-Specific Code Examples
Contoh:
- English: Menampilkan contoh konfigurasi dalam bahasa Ruby
- Indonesian: Menampilkan versi bahasa Indonesia dengan komentar sesuai lokal
nav_key.
Kesimpulan
Dengan mengintegrasikan GitHub Gist ke dalam Jekyll multilingual docs, Anda dapat:- Mengelola snippet kode di luar repositori
- Mendukung banyak bahasa tanpa duplikasi
- Memungkinkan user berkontribusi tanpa pull request ke Jekyll
Solusi ini ringan, fleksibel, dan cocok untuk dokumentasi open source yang terus berkembang.
Next Up (Optional):
Mau saya lanjutkan dengan sistem caching atau fallback jika embed Gist gagal, atau membuat halaman index Gist multilingual untuk navigasi semua snippet?
