Perihal objek YAML bagi bahagian awal laman Jekyll

[kmubiin]

TERABAI: Isu ini akan dirujuk dan dipetik semula oleh isu yang lebih baharu (belum dicipta pada masa ini). Dengan itu, isu ini dianggap terabai pasca-2021.

---

Isu ini dicipta untuk melaporkan kelainan tiga baris pertama dalam semua fail di docs/ untuk memapar laman utama (GitHub Pages). Penyelesaian bagi isu ini adalah sama ada membetulkan ruang kosong antara pasangan sempang-tiga --- atau menambah satu objek YAML untuk kegunaan tertentu.

Menurut penerangan laman Jekyll tentang Front Matter:

Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines [...]

Front Matter Variables Are Optional: If you want to use Liquid tags and variables but don’t need anything in your front matter, just leave it empty! The set of triple-dashed lines with nothing in between will still get Jekyll to process your file [...]

Apa yang pasti, pasangan sempang-tiga --- mesti hadir dalam fail Markdown supaya dapat dikerjakan oleh Jekyll untuk memapar laman utama. Dan lagi, sebarang anu antara pasangan sempang-tiga adalah sekadar pilihan dan tidak perlu digunakan.

Penjelasan: Tajuk "memapar laman utama" adalah tidak tepat. Istilah Inggeris "front matter" ialah "bahagian awal" dalam bahasa Melayu berdasarkan carian bersahaja--rujuk Buku di Wikipedia dan lihat di bawah tajuk "Struktur buku".

Sebaliknya, apa yang kurang pasti adalah ruang kosong antara pasangan sempang tiga. Penerangan di atas "triple-dashed lines with nothing in between" adalah sama ada: tiada apa di antaranya, atau ada baris kosong tetapi tiada apa di antaranya--agak mengelirukan.

Bukti salah: Selama ini, M menganggap "nothing in between" sebagai "tiada apa di antaranya" tetapi hakikatnya anggapan ini mungkin salah. Hal ini disokong oleh bukti cubaan:

[WARNING] Could not parse YAML metadata at line 4 column 1: not an object

Pertama, terdapat amaran daripada garis perintah pandoc apabila cuba menukar Markdown ke HTML untuk paparan cubaan di luar talian. Kedua, amaran tersebut tidak kelihatan apabila baris kosong atau satu objek YAML seperti layout: default ditambah di antaranya. Kelainan ini tidak dijelaskan di laman Jekyll, tetapi boleh dipastikan melalui cubaan sendiri.

Bukti betul: Terdapat satu contoh "tiada apa di antaranya" di laman Jekyll tentang Assets yang mencadangkan cara ini mungkin betul bagi Jekyll sahaja.

Jekyll provides built-in support for Sass and can work with CoffeeScript via a Ruby gem. In order to use them, you must first create a file with the proper extension name (one of .sass, .scss, or .coffee) and start the file with two lines of triple dashes, like this:

---
---

// start content
.my-definition
  font-size: 1.2em

Bagaimanapun, perlu membuat cubaan lanjut untuk memahami pepijat ini. Mungkin juga ada objek YAML yang berguna untuk laman utama projek suaikata berbanding hanya dibiar kosong.

Terbitan yang terjejas: 1.0 ... (semua terbitan siri pertama) Terbitan dalam rancangan: ~Beta~ semasa

---

22 Jul: Pepijat ini tidak bermasalah dan cuma mengelirukan, tangguh rancangan ke Beta

1 Ogo: Penjelasan dan pembetulan tajuk isu ini.

6 Ogo: Cuba objek YAML di laman tertentu (rujuk c9cf714) dan juga tetapan laman _config.yml (rujuk 2958217), pembetulan pada nota kaki ini. Objek khas seperti layout: null adalah objek YAML bagi Jekyll, manakala objek lazim seperti anu: nilai adalah objek YAML yang boleh dicapai menggunakan Liquid (rujuk #41 perihal objek Liquid).

7 Ogo: Objek YAML yang wajar digunakan mungkin sekali: category: nama|categories: nama1 nama2 dan tag: ciri|tags: ciri1 ciri2--rujuk posts--dan berguna untuk mempapar senarai semua laman yang berkenaan melalui objek Liquid dengan {{ site.categories.nama }} dan {{ site.tags.ciri }}--rujuk variables--untuk kemas kini laman bersuai dengan sendiri. Belum cuba lagi.

8 Ogo: Sudah cuba. Objek category: cuba perlu diguna bersama 'for' seperti {% for post in site.categories.cuba %} dan diiringi dengan tag Markdown atau HTML seperti <ul><li><a href="{{ site.url }}{{ post.url }}">{{ post.title }}</a></li></ul> dan akhirnya tutup dengan {% endfor %}. Dan lagi, fail perlu disimpan dalam _posts dan perlu diberi nama seperti 2020-08-08-contoh.md untuk berhasil. Agak terhad dan leceh. Lagi, kalau guna collections masih perlu cipta folder _nama tetapi tidak perlu ada nama khusus sepertimana _posts. Tapi ini kelihatan lagi leceh sebab ada lagi tetapan lain yang perlu dibuat. Lupakan objek category dan juga tag. Fikir cara lain.

11 Ogo: Baris kosong selepas sempang-tiga tidak diperlukan dan terbukti (b0d1982).

13 Ogo: Guna objek sendiri asal: bagi menyatakan tempat fail berkenaan tersimpan ( 41f1932). Ini adalah petunjuk tambahan yang menyatakan alamat relatif folder sahaja, dan tidak seperti objek terbina page.path: yang menyatakan alamat penuh fail berkenaan di laman sumber.

9 Sep: Isu ini dianggap isu berkecuali, berlaku sebelum Beta.

5 Dis: Objek sendiri asal: diganti dengan objek global published: yang memberi pilihan berguna untuk kecualikan mana-mana laman daripada diterbit (b9de8fa).