Membuat Blog Menggunakan Pelican dan Tema Bootstrap3

Bagaimana blog seperti yang sedang anda baca ini dibuat dengan mudah menggunakan Pelican dan Bootstrap Theme?¶

Mengapa menggunakan Pelican?¶

Menulis blog dengan pure handcoded dapat sangat melelahkan. Formatting, pengaturan layout, dan menambahkan features secara manual membutuhkan pengetahuan dasar pengembangan website yang cukup baik. Pelican hadir membantu proses automasi pada skema static website (HTML) dengan content template dan features yang sangat lengkap, ditambah lagi kita dapat menggunakan berbagai macam tema dari koleksi Pelican Themes.

Pengetahuan dasar yang harus dimiliki¶

Meskipun Pelican mengatur sebagian besar proses automasi, tetap dibutuhkan pengetahuan dasar dalam penggunaannya. Minimal hal ini akan membantu dalam proses debugging apabila terjadi kesalahan dalam presetting file configurasi. Adapun kemampuan dasar yang harus dimiliki adalah sebagai berikut :

• Dasar Python,pelican ditulis dalam bahasa Python dimana seluruh konfigurasi file ditulis dalam Python sehingga pengetahuan dasar akan sangat membantu.
• Dasar Git dan GitHub, pada artikel ini akan menggunakan tools Github Pages pada proses deployment. Ini sangat bagus mengingat GitHub Pages gratis dan mudah digunakan, di lain sisi GitHub sangat baik dalam proses automasi, pengembangan, kolaborasi dan pengarsipan source code dan resources dari halaman blog yang dimiliki.
• Dasar Static Website Development, dengan anda membaca artikel ini diasumsikan bahwa anda memiliki minimal pengetahuan dalam teknologi pengembangan static website seperti HTML, JQuery, JavaScript, dan CSS. Kemampuan ini akan sangat berguna apabila menginginkan kustomisasi yang lebih lanjut pada template theme yang sudah ada, atau bahkan saat anda ingin membuat template dan theme sendiri :}.
• Dasar Markdown dan Jupyter Notebook, contents blog Pelican yang akan anda deploy pada Github Pages nantinya ditulis dalam format Markdown. Kapabilitas lain yang sangat luar biasa dari Pelican adalah kemampuan untuk rendering artikel dengan format Jupyter Notebook kedalam static html tanpa membutuhkan intervensi pemformatan tambahan melalui tangan anda. Pengetahuan Jupyter Notebook dan Markdown language akan sangat berguna apalagi jika blog anda bertemakan, Data Science atau Machine Learning khususnya dalam bahasa Python.

Alat dan Bahan¶

Berikut adalah tools yang harus terinstall pada driver anda :

• Command Line Interface (CLI) (Terminal, Command Prompt, Etc)
• Python 3
• Git
• VSCode atau IDE lainnya

1. Instalasi Pelican

Membuat Environment Kerja Baru¶

Sebelum menginstal Pelican ada baiknya membuat virtual environment pada area kerja anda untuk mencegah inner-conflict atau kerusakan pada global environment python yang sudah ada. Untuk itu digunakan tool virtualenv.

virtualenv dapat dengan mudah diinstal menggunakan pip.

pip install virtualenv

Kemudian untuk membuat virtual environment di area kerja anda gunakan command berikut ini:

virtualenv ~/myproject/project_pelican ##contoh area kerja anda
cd ~/myproject/project_pelican ##masuk ke area kerja
source bin/activate ##aktivasi area kerja

Instal Pelican¶

Lalu instal Pelican menggunakan pip pada area kerja

python -m pip install pelican

untuk upgrade pelican

python -m pip install --upgrade pelican

Pelican Quickstart¶

Setelah Pelican terinstal pada area kerja yang diinginkan, saatnya memulai membangun blog anda.

pelican-quickstart

perintah ini akan memunculkan beberapa pertanyaan awal mengenai website yang akan ada bangun.

Berikut adalah daftar pertanyaan dan jawaban yang harus anda isikan:

❯ pelican-quickstart
Welcome to pelican-quickstart v4.7.2.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] my_project
> What will be the title of this web site? your site name
> Who will be the author of this web site? me
> What will be the default language of this web site? [en] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10] 10
> What is your time zone? [Europe/Rome] Asia/Jakarta
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) y
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) n
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at /home//myproject/project_pelican/my_project

Kemudian file project anda akan muncul secara otomatis dengan hierarki file sebagai berikut ini :

yourproject/
├── content
│   └── (pages)
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

2. Instalasi Pelican-Bootstrap3 Themes

Pelican Bootstrap 3 adalah tema yang responsive, simpel, dengan fitur-fitur yang sangat lengkap. Blog yang sedang anda baca ini secara teknis juga dibangun dengan mengembangkan tema Pelican Bootsrap 3.

Langkah pertama :

Clone repository tema bootstrap3 pada github dengan menggunakan git

git clone https://github.com/getpelican/pelican-themes.git

kemudian taruh folder pelican-bootstrap3 didalam folder dengan nama theme pada area kerja yang sebelumnya sudah dibuat secara otomatis oleh pelican-quickstart.

Sehingga hierarki folder project anda akan seperti berikut ini.

yourproject/
├── content
│   └── (pages)
├── theme                # put your theme here
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

Jika anda memiliki kemampuan yang baik pada teknologi web development, pada dasarnya anda dapat membuat tema sendiri dengan mengikuti hierarki file seperti berikut ini.

theme
├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         # to display archives
    ├── period_archives.html  # to display time-period archives
    ├── article.html          # processed for each article
    ├── author.html           # processed for each author
    ├── authors.html          # must list all the authors
    ├── categories.html       # must list all the categories
    ├── category.html         # processed for each category
    ├── index.html            # the index (list all the articles)
    ├── page.html             # processed for each page
    ├── tag.html              # processed for each tag
    └── tags.html             # must list all the tags. Can be a tag cloud.

Kemudian anda dapat membuat skema HTML, JavaScript, dan CSS sesuai dengan keinginan anda dan kemudian biarkan Pelican melakukan proses automasi untuk anda.

3. Instalasi Pelican Plugins

Langkah selanjutnya adalah menginstal plugins yang dibutuhkan Pelican agar dapat melakukan rendering file pada folder content baik itu dengan format jupyter-notebook.ipynb ataupun markdown.md untuk diubah kedalam file static website yang sedang anda bangun.

Langkah pertama :

clone repository pelican-plugins dari GitHub dengan menggunakan git

git clone --recursive https://github.com/getpelican/pelican-plugins

kemudian taruh file pelican-plugins kedalam folder kerja sehingga hierarki folder menjadi seperti berikut ini.

yourproject/
├── content
│   └── (pages)
├── theme                # put your theme here
├── pelican-plugins      # all the plugins sit here
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

4. Menulis Konten Blogs

Pelican dapat mengenali file konten dengan baik melalui metadata. Seperti halnya judul, slug, summary, category dan author dari konten yang ingin anda posting. Pada dasarnya pelican mengenali file konten dengan format .rst dan .md. Namun pada artikel ini akan dibahas konten dengan format Markdown dengan ekstensi file .md.

Untuk itu sebelumnya anda harus menginstal markdown package terlebih dahulu dengan menggunakan pip

pip install markdown

pada lingkungan (environtment) kerja.

Contoh syntax metada untuk sebuah postingan dengan format markdown adalah seperti berikut ini.

Title: My First Blog
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: My Self
Summary: Short version for index and feeds

Write your content in markdown style here

anda dapat menulis file diatas menggunakan IDE seperti VSCode, Atom, Kate,Notepad++ dan lain sebagainya. Satu baris setelah Summary anda dapat menulis apapun sesuka hati untuk konten blog pertama anda. Kemudian menyimpannya dengan ekstensi file .md. Sebagai contoh anda menulis artikel pertama anda dengan nama blog_pertamaku.md.

Lalu bagaimana dengan file gambar saya?¶

Tentu saja anda ingin menaruh banyak informasi visual pada blog anda. Tenang saja, Pelican sudah paham karakterstik dan perilaku suatu static website. Pada markdown file yang telah anda tulis anda dapat menambahkan gambar dengan menggunakan syntax berikut ini.

1. Open the file .
2. which file

    ![Debian, the Linux distro](../image/debian-log.png)

3. Close the file.

Output Syntax diatas akan menjadi:¶

1. Open the file .

2. which file

   

3. Close the file.

Bila anda perhatikan ../image/debian-log.png merupakan relatif link. Perilaku ini dapat di implementasikan dengan menginisiasi static folder pada Pelican dengan melakukan pengaturan pada pelicanconf.py file. Static folder adalah folder yang akan diduplikasi kedalam output file seperti apa adanya.

Untuk itu anda harus mengatur STATIC_PATHS setting pada file pelicanconf.py, contohnya seperti berikut ini:

STATIC_PATHS=['image','notebooks'] #selain folder image, anda juga dapat menambahkan folder lain dalam list

Sehingga hierarki folder kerja anda akan seperti berikut ini.

yourproject/
├── content
│   ├── image
│   │   └── debian-logo.png               # your file image
│   ├── notebooks
│   │   └── your_notebook.ipynb           # notebook file 
│   └── pages                             # your pages folder
│       └── blog_pertamaku.md             # your content file
├── theme                                 # put your theme here
├── pelican-plugins                       # all the plugins sit here
├── output                                # All pages ready to deploy are sitting here
├── tasks.py
├── Makefile
├── pelicanconf.py                        # Main settings file
└── publishconf.py                        # Settings to use when ready to publish

Saya ingin bagikan artikel based on Python Jupyter Notebook yang saya miliki, bagaimana caranya ??¶

Diatas sudah dibahas bagaimana membuat konten blog menggunakan pure markdown language style. Secara teknis markdown language sangatlah mumpuni dalam membangun konten blog anda, batasannya hanyalan imajinasi dan kreatifitas anda saja.

Namun ada cari lain yang lebih fancy yaitu menggunakan file Python Notebook yang anda miliki. Dengan begini anda tidak perlu lagi susah payah reformatting baris kode python anda sehingga dapat dimengerti oleh browser. Hanya dengan menggunakan beberapa plugins dari Pelican, maka notebook anda siap untuk di publikasikan.

Ayo kita mulai!!¶

Untuk memulai, pastikan anda mengatur PLUGIN_PATHS, MARKUP, dan mengaktifkan beberapa PLUGINS lainnya pada file pelicanconf.py seperti berikut ini.

PLUGIN_PATHS=['pelican-plugins']
MARKUP = ('md')
PLUGINS = ['sitemap',
           'i18n_subsites', 'related_posts',
           'liquid_tags.img', 'liquid_tags.video',
           'liquid_tags.youtube', 'liquid_tags.vimeo',
           'liquid_tags.include_code',
           'tipue_search',
           'summary', 'feed_summary',
           'liquid_tags.notebook'
           ]

Nah, dengan begitu maka semua plugins yang dibutuhkan sudah tersetting dengan benar.

Selanjutnya anda perlu mengaktifkan direktori lokasi penyimpanan file notebook anda (berekstensi .ipynb) pada file pelicanconf.py seperti berikut ini

NOTEBOOK_DIR='notebooks'

bila anda ingat tahap sebelumnya, direktori diatas juga telah diatur sebagai STATIC_PATHS.

Sama halnya dengan menggunakan pure markdown style, pada proses ini kita juga perlu membuat file metadata dengan format markdown berekstensi .md, hanya saja pada bagian area konten melainkan menulisnya dalam pure markdown kita malah beritahu Pelican untuk melihat file notebook yang telah kita miliki dengan menambahkan syntax berikut ini

{% notebook filename.ipynb %}

maka secara keseluruhan, file markdown akan seperti berikut ini

Title: Your Blog Title
Tags: python, visualization
Date: 2022-03-08
Modified: 2022-03-18
Slug: your-blog-title
Summary: {% notebook my_Notebook.ipynb cells[1:2] %}

{% notebook my_Notebook.ipynb cells[:] %}

anggaplah file kedua ini merupakan post kedua dari blog anda, sehingga anda akan menyimpannya sebagai blog_keduaku.md maka hierarki folder anda secara keseluruhan adalah seperti berikut ini.

yourproject/
├── content
│   ├── image
│   │   └── debian-logo.png               # your file image
│   ├── notebooks
│   │   └── your_notebook.ipynb           # notebook file 
│   └── pages                             # your pages folder
│       ├── blog_pertamaku.md             # your pure markdown style post
│       └── blog_keduaku.md               # Your Fancy Jupyter Notebook post :)                                         
├── theme                                 # put your theme here
├── pelican-plugins                       # all the plugins sit here
├── output                                # All pages ready to deploy are sitting here
├── tasks.py
├── Makefile
├── pelicanconf.py                        # Main settings file
└── publishconf.py                        # Settings to use when ready to publish

Bagaimana dengan fitur website lainnya?? Apakah juga diatur pada file pelicanconf.py??¶

Tentu saja.

Pelican-Themes menyediakan berbagai fitur yang sangat menunjang performa blog anda. Mulai dari disqus comment, Google Analytics, AddThis, Archive, License, dan lain sebagainya. Penjelasan lebih lengkap ada pada masing-masing dokumentasi dari tema yang anda pilih.

Pada artikel ini, kita menggunakan Pelican-Boorstrap3. Untuk detail lebih lanjut silahkan kunjungi dokumentasi lengkapnya disini.

Dan ya tentu saja, seluruh pengaturan fitur tambahan harus anda masukan kedalam file pelicanconf.py. Jika anda masih kesulitan memahami file konfigurasi ini, silahkan kunjungi source code dari blog ini KLIK DISINI, anda dapat melihat bagaimana pelicanconf.py memetakan perilaku, bentuk, dan style dari blog anda.

4. Memproduksi Blog Site

Setelah anda tahu bagaimana cara menulis konten pada blog anda serta bagaimana melakukan pengaturan pada file pelicanconf.py dan mengoptimalisasi fitur pada tema yang anda pilih. Langkah selanjutnya adalah memproduksi file static website anda, yang mana file ini nantinya akan tersimpan pada folder output. File-file didalam folder output telah diatur sedemikian rupa oleh Pelican untuk dapat segera dipublikasikan dimanapun juga, tapi pada artikel ini kita hanya kan membahas deployment pada GitHub Pages.

Mari kita mulai!!¶

Ada beberapa opsi yang dapat anda pilih, untuk detail lebih lanjut anda dapat mengunjugi laman berikut ini.

Namun untuk kali ini kita akan menggunakan make. Masih pada area kerja yang sama anda dapat menuliskan perintah berikut pada terminal

make html

Jika anda ingin menambahkan pengaturan pada file publishconf.py, maka anda dapat menjalankan perintah

make publish

format file publishconf.py pada dasarnya adalah sebgaai berikut ini

# This file is only used if you use `make publish` or
# explicitly specify it as your config file.

import os
import sys
sys.path.append(os.curdir)
from pelicanconf import *

# If your site is available via HTTPS, make sure SITEURL begins with https://
SITEURL = 'Your URL site'   ## cermati bagian ini
RELATIVE_URLS = False

FEED_ALL_ATOM = 'feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'feeds/{slug}.atom.xml'

DELETE_OUTPUT_DIRECTORY = True

# Following items are often useful when publishing

DISQUS_SITENAME = "your disqus_site_name"
GOOGLE_ANALYTICS = "your_GA_Code"

Untuk mereview bagaimana tampilan website anda pada localhost, maka jalankan perintah berikut ini

make serve

Informasi lebih detail dapat anda peroleh pada laman dokumentasi resmi Pelican atau dengan melihat source code blog ini.

Kemudian hierarki akhir dari folder kerja anda akan menjadi seperti berikut ini.

yourproject/
├── content
│   ├── image
│   │   └── debian-logo.png               # your file image
│   ├── notebooks
│   │   └── your_notebook.ipynb           # notebook file
│   └── pages                             # your pages folder
│       ├── blog_pertamaku.md             # your pure markdown style post
│       └── blog_keduaku.md               # Your Fancy Jupyter Notebook post :)                                         
├── theme                                 # put your theme here
├── pelican-plugins                       # all the plugins sit here
├── output                                # All pages ready to deploy are sitting here
│      ├── tag
│      ├── post
│      ├── archive
│      │     ├── march
│      │     ├── june
│      │     └── august
│      ├── index.html                    # Your index.html file
│      └── archives.html
│                                          
├── tasks.py
├── Makefile
├── pelicanconf.py                        # Main settings file
└── publishconf.py                        # Settings to use when ready to publish

5. Deployment pada GitHub Pages

Membuat akun GitHub¶

Langkah pertama adalah anda harus mempunyai GitHub akun. Daftarkan akun anda dengan username yang representatif terhadap blogs yang sedang anda buat. Sebagai contoh, jika anda fungsikan blog sebagai portfolio dari perusahaan anda dengan nama xcompany, maka buatlah username tersebut pada GitHub.

Membuat Repositori¶

kemudian buatlah sebuah repositori, repositori tersebut harus dinamai seperti berikut ini

your_GitHub_username.github.io

Anda dapat uncheck Add Readme pada pilihan bagian bawah Kemudian pilih create repository, maka anda akan beralih ke halaman selanjutnya. Dengan begitu tahap pembuatan repository telah selesai.

Pushing Static File Anda ke Repositori¶

Untuk memindakan seluruh file static yang telah anda hasilkan di dalam folder output menuju repositori maka anda harus masuk pada direktori output terlebih dahulu dengan menjalankan perintah seperti berikut ini.

cd output

kemudian inisiasi folder output tersebut sebagai local repositori terlebih dahulu dengan menjalankan perintah

git init

Tambahkan seluruh file didalam folder output dari working direktory menuju staging area dan lakukan commit statement dengan menjalankan perintah

git add .
git commit -m "First Commit"

kemudian masuk pada branch main sebagai default pada GitHub dengan menjalankan perintah

git branch -M main

Tambahkan remote repositori dengan perintah

git remote add origin https://github.com/repo_name/repo_name.git

Dan lakukan push sebagai tahap akhir

git push -u origin main

... dan anda pun telah seselai :)¶

Segera kunjungi username.github.io pada browser untuk melihat indahnya mahakarya yang telah anda buat :)¶

Bagaimana menurut anda?, apakah bermanfaat?.¶

Terima kasih telah berkunjung :)¶