Satu berkas untuk satu tulisan
Setiap tulisan memiliki satu berkas Markdown datar. Nama berkas menggunakan huruf kecil dan tanda hubung, lalu menjadi slug pada alamat tulisan.
Contoh tersebut diterbitkan sebagai /tulisan/judul-tulisan/. Media biasa tidak
berada di folder Markdown; folder media dengan slug yang sama merupakan
konvensi Shaurastro di dalam media repositori Tina.
Frontmatter yang diperlukan
Tulisan baru sekurang-kurangnya memiliki metadata berikut:
Tanggal harus berupa string kalender YYYY-MM-DD. Shaurastro tidak
menafsirkannya sebagai waktu tengah malam sehingga tanggal tidak bergeser saat
build berjalan di zona waktu lain.
Markdown dan MDX
Gunakan <slug>.md untuk hampir seluruh kebutuhan. Judul, daftar, tabel, kutipan,
gambar, kode, dan elemen semantik seperti <kbd> dapat ditulis dalam Markdown.
Gunakan <slug>.mdx hanya ketika isi artikel benar-benar memerlukan komponen.
Batang nama berkas tetap menjadi slug tulisan.
Kode, tombol papan ketik, dan tabel
Gunakan fence dengan pengenal bahasa agar Shiki dapat menyorot kode saat build:
Bagian title="..." bersifat opsional dan hanya menerima satu judul teks.
Judul dapat berisi spasi serta tanda baca dan selalu di-escape sebagai teks,
bukan HTML. Fence tanpa judul tetap berfungsi; bahasa yang dikenal dapat
menjadi label ringkas, sedangkan teks polos tidak dipaksa memiliki metadata.
Setiap baris kode memperoleh nomor visual mulai dari 1, termasuk baris kosong. Nomor tidak menjadi bagian dari teks sumber. Setelah JavaScript copy siap, tombol Salin muncul. Salinan berisi kode mentah saja—tanpa nomor baris, judul, label bahasa, atau status tombol. Keberhasilan menampilkan Tersalin, kegagalan menampilkan Gagal, dan keduanya diumumkan melalui status sopan yang lokal pada blok tersebut. Tanpa JavaScript atau Clipboard API, tombol tidak ditampilkan dan kode tetap dapat dibaca serta digulir.
Untuk input pengguna, pertahankan elemen semantik:
Tabel memakai sintaks GFM biasa. Penanda :---, :---:, dan ---: tetap
mengatur perataan kolom. Pada layar sempit, wrapper lokal dapat difokuskan dan
digulir tanpa mengubah semantik <table> atau memperlebar halaman.
Admonisi Markdown
Lima jenis admonisi tersedia langsung di berkas Markdown:
Label yang tampil adalah Catatan, Kiat, Penting, Peringatan, dan Bahaya. Paragraf, daftar, tautan, kode sebaris, serta fence kode dapat ditulis di dalamnya. Admonisi tidak membuat heading baru sehingga labelnya tidak masuk daftar isi. Jenis yang tidak didukung dan admonisi bertingkat menghentikan build dengan pesan yang jelas.
Menambahkan media repositori
Unggah gambar di bawah folder media yang sama dengan slug tulisan, kemudian gunakan jalur publik berakar:
Gambar sampul memakai objek cover agar tata letaknya dapat distandardisasi
pada posisi pembuka tulisan:
Jangan menambahkan nama berkas ke frontmatter sebelum asetnya benar-benar ada. Astro memvalidasi pola jalur dan kecocokan folder slug saat build.
Sampul bersifat opsional dan dikendalikan oleh tata letak tema. Gambar biasa
tetap dapat diletakkan langsung di dalam Markdown ketika posisinya merupakan
bagian dari alur artikel. Tema tidak otomatis menyalin sampul ke dalam isi
artikel, dan alt wajib diisi ketika objek cover digunakan. Penyajian visual
menempatkan sampul setelah metadata tulisan dan sebelum isi artikel, tanpa
memotong proporsi sumbernya.
Gambar Markdown mandiri dengan teks alternatif bermakna ditampilkan secara responsif dan menjadi tautan ke berkas sumber beresolusi penuh:
Tautan gambar terbuka di tab baru dan tetap dapat digunakan dengan papan ketik tanpa JavaScript. Gambar sebaris dan tujuan tautannya memakai aset unggahan publik yang sama. Proporsi, teks alternatif, dan keterangan yang tersedia tetap dipertahankan.
Gambar sampul tidak berada di dalam isi artikel sehingga tidak diproses. Gambar yang sudah berada di dalam tautan juga selalu dikecualikan:
Tautan buatan penulis selalu berwenang dan tidak dibungkus ulang. Gambar sampul juga tetap mengikuti komponen sampulnya sendiri.
Susunan halaman tulisan
Kepala tulisan menampilkan judul, tanggal publikasi dengan nama bulan lengkap, dan kategori dalam satu susunan terpusat. Tanggal serta kategori dipisahkan oleh tanda titik tengah:
Jika tersedia, tanggal pembaruan berada pada baris berikutnya. Lisensi tulisan atau lisensi bawaan muncul sesudahnya. Setelah isi artikel selesai, tagar tetap mengikuti urutan frontmatter dan setiap tagar mengarah ke halaman taksonominya.
Navigasi kronologis berada setelah pemisah tipis. Pada layar sempit, Tulisan sebelumnya yang lebih lama muncul lebih dahulu, kemudian Tulisan berikutnya yang lebih baru.
Mengaktifkan daftar isi
Tambahkan toc: true pada frontmatter ketika artikel memiliki struktur bagian
yang cukup panjang:
Daftar isi hanya memasukkan h2 dan h3 dari isi artikel serta baru
ditampilkan jika sekurang-kurangnya dua judul memenuhi syarat. Judul tulisan
tetap menjadi satu-satunya h1 halaman. Jangan menulis daftar isi kedua secara
manual di dalam Markdown.
Pada layar lebar, daftar isi berada sebagai sidebar kanan di luar kolom
paragraf. Lebar paragraf tetap 44rem dan sumbu artikel tidak bergeser. Pada
layar yang lebih kecil, Daftar Isi tampil sebagai panel native yang
tertutup secara baku setelah sampul opsional dan sebelum isi artikel.
Ketika JavaScript tersedia, bagian yang sedang dibaca memperoleh penanda pita tipis. Tanpa JavaScript, seluruh tautan jangkar, sidebar lengket, dan panel native tetap dapat digunakan; hanya penanda bagian aktif yang tidak muncul.
Navigasi kronologis
Shaurastro mengurutkan tulisan dari nilai published terbaru ke terlama.
Tanggal updated hanya menjelaskan pembaruan isi dan tidak memindahkan tulisan
di beranda, arsip, atau navigasi antar-tulisan.
Pada halaman tulisan, hubungan navigasinya dibaca sebagai berikut:
- Tulisan sebelumnya menunjuk ke tulisan yang lebih lama.
- Tulisan berikutnya menunjuk ke tulisan yang lebih baru.
- Tulisan terbaru tidak memiliki tetangga yang lebih baru.
- Tulisan terlama tidak memiliki tetangga yang lebih lama.
- Tulisan berstatus draf tidak ikut dalam navigasi publik.
Gunakan string kalender untuk kedua tanggal:
Lisensi tulisan
Sebuah tulisan dapat menentukan lisensinya sendiri:
Nilai url boleh dihilangkan untuk lisensi yang tidak memiliki tautan:
Lisensi pada frontmatter selalu menggantikan defaultLicense di
src/config.ts. Ketika objek license tidak ada, tema memakai lisensi bawaan
yang dikonfigurasi. Jika defaultLicense juga diatur menjadi null, blok
lisensi tidak ditampilkan. Tema mempertahankan nama dan URL yang diberikan;
tema tidak menebak URL atau jenis lisensi dari namanya.
Gambar sampul
Objek cover hanya digunakan jika tulisan memang memiliki gambar pembuka yang
akan ditempatkan oleh tata letak tema:
Berkas sampul.webp berada di
public/uploads/posts/judul-tulisan/, dan alt wajib menjelaskan informasi
visualnya. Gambar lain yang menjadi bagian dari uraian tetap ditulis di dalam
alur Markdown:
Jangan memakai sampul dan gambar isi sebagai duplikasi otomatis. Pipeline menyiapkan data gambar yang tervalidasi, sedangkan halaman tulisan menempatkan sampul opsional itu sebelum isi Markdown.