Markdown dan Command Line Interfaces

Menulis Teks dengan Markdown

Markdown adalah bahasa markup ringan $untuk menyatakan struktur dokumen dalam teks biasa$ . Judul, daftar, tautan, blok kode, dan tabel tetap mudah dibaca di sumber serta dapat dirender menjadi HTML atau format lain.

Source file yang mudah dibaca adalah keunggulan utama Markdown. Kamu dapat meninjau perubahan baris demi baris, menyimpan source file Markdown di Git, dan membiarkan renderer menentukan tipografi akhir. Struktur dokumen tetap terlihat langsung di source file.

Sintaks Dasar Markdown

Contoh berikut mengumpulkan sintaks umum dalam satu file. $Tanda pagar di awal baris$ membuat heading. Penanda di sekeliling teks dapat membuat penekanan, tautan, atau kode.

Contoh memakai fitur Markdown yang didukung Pandoc dan GitHub Flavored Markdown. Tabel dan coretan ~~teks~~ merupakan ekstensi, jadi tidak semua renderer Markdown menampilkannya. Perintah shell berikut memakai Bash di macOS atau Linux. Contoh path perlu disesuaikan dengan folder latihanmu.

basic-syntax.md

# Heading Level 1
## Heading Level Dua
### Heading Level Tiga

**Bold text**
*Italic text*
~~Strikethrough text~~

> Blockquote untuk kutipan penting

1. Ordered list item pertama
2. Ordered list item kedua
3. Ordered list item ketiga

- Unordered list item
- Item lainnya
- Item terakhir

[Link text](https://example.com)
![Alt text](image.jpg)

`inline code`

```python
# Code block
def hello_world():
  print("Hello, World!")
```

---

| Kolom 1 | Kolom 2 | Kolom 3 |
|---------|---------|---------|
| Data A  | Data B  | Data C  |
| Data D  | Data E  | Data F  |

Alur Kerja Markdown

Simpan source file sebagai $berkas utama yang ditinjau$ . Hasil render dapat dibuat ulang dari berkas ini. Alurnya terdiri atas membuat, mengedit, memvalidasi, mengonversi, lalu melihat preview.

Buat file berekstensi .md, tulis isinya, lalu konversi dengan tool seperti Pandoc. Dengan --standalone, HTML memuat header dan body dokumen lengkap. Gambar dan stylesheet yang ditautkan tetap terpisah kecuali sengaja disematkan. Output PDF juga memerlukan PDF engine yang kompatibel di perangkatmu.

markdown-workflow.sh

# Membuat file markdown baru
touch document.md

# Edit dengan text editor
nano document.md

# Konversi ke HTML menggunakan pandoc
pandoc document.md --standalone -o document.html

# Konversi ke PDF jika mesin PDF yang didukung telah terpasang
pandoc document.md -o document.pdf

# Pratinjau di macOS. Desktop Linux umumnya memakai xdg-open
open document.html

Dasar Antarmuka Baris Perintah

Antarmuka baris perintah atau CLI menerima $perintah teks melalui shell$ . Setiap perintah memiliki nama program, flag opsional, dan argumen seperti path.

CLI berguna karena perintah dapat diperiksa, diulang, dijadikan skrip, dan ditinjau. Path dan flag destruktif harus ditulis dengan tepat karena shell mengikuti perintah tersebut apa adanya. Periksa perintah sebelum menjalankannya.

Navigasi dan Eksplorasi Direktori

Sebelum mengubah file, pastikan $direktori aktif$ , periksa isinya, lalu berpindahlah dengan path yang eksplisit:

navigation-commands.sh

# Menampilkan direktori kerja saat ini
pwd

# Melihat isi direktori
ls
ls -l    # format detail
ls -la   # termasuk file tersembunyi

# Berpindah direktori
mkdir -p "$HOME/markdown-practice"
cd "$HOME/markdown-practice"
cd ..    # naik satu level
cd ~     # ke home directory
cd -     # kembali ke direktori sebelumnya

# Membuat direktori baru
mkdir new_project
mkdir -p project/src/components  # buat hierarki direktori

Operasi File dan Direktori

Perintah file langsung bekerja pada path nyata. $Periksa target sebelum menghapus$ , kutip path yang mungkin memuat spasi, dan hindari flag force rekursif kecuali direktori tepatnya sudah terbukti boleh dibuang.

file-operations.sh

# Menyalin file
cp source.txt destination.txt
cp -r source_folder/ destination_folder/

# Memindahkan atau mengganti nama file
mv old_name.txt new_name.txt
mv file.txt /path/to/new/location/

# Periksa sebelum menghapus
pwd
ls -la unwanted_folder
rm unwanted_file.txt
rm -r unwanted_folder  # Menghapus seluruh isi folder dan tidak dapat dibatalkan. Periksa path ini dahulu

# Melihat isi file
cat file.txt        # tampilkan seluruh isi
head -10 file.txt   # 10 baris pertama
tail -10 file.txt   # 10 baris terakhir
less file.txt       # view dengan navigasi

Integrasi Markdown dengan CLI

Skrip build kecil menjalankan langkah konversi yang sama setiap kali. Skrip harus $gagal ketika sebuah perintah gagal$ , membuat direktori output sendiri, mengutip setiap path, dan menangani keadaan tanpa file sumber:

markdown-cli-workflow.sh

# Setup proyek markdown
mkdir my-documentation
cd my-documentation

# Struktur direktori
mkdir -p {src,build,images,assets}

# Buat file markdown
touch src/index.md src/getting-started.md src/api-reference.md

# Otomatisasi build dengan script
cat << 'EOF' > build.sh
#!/bin/bash
set -eu

echo "Building documentation..."
mkdir -p build

# Konversi semua file .md ke .html
for file in src/*.md; do
  [ -e "$file" ] || continue
  basename=$(basename "$file" .md)
  pandoc "$file" -o "build/$basename.html" --standalone
  echo "Converted: $file -> build/$basename.html"
done

echo "Build completed!"
EOF

# Buat script executable
chmod +x build.sh

# Jalankan build
./build.sh

Alat CLI untuk Markdown

Gunakan kanal pemasangan resmi setiap alat, lalu $verifikasi perintah yang terpasang$ sebelum mengandalkannya di dalam skrip. Pandoc mengonversi dokumen, sedangkan linter Markdown memeriksa konvensi sumber:

markdown-tools.sh

# Verifikasi alat yang diperlukan
command -v pandoc
command -v markdownlint

# Periksa sumber Markdown
markdownlint "docs/**/*.md"

# Konversi Markdown ke berbagai format
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o output.epub

# Dengan template custom
pandoc input.md -o output.html --template=custom.html

Praktik Terbaik CLI dan Markdown

Simpan source file Markdown di version control. $Validasi file sebelum konversi$ , simpan hasil konversi di direktori output yang dapat dibuat ulang, lalu tinjau diff sebelum commit:

Direktori site di contoh ini khusus untuk output hasil konversi dan akan diganti. Simpan file yang kamu tulis di docs, bukan di site.

best-practices.sh

# Build dokumentasi lokal yang dapat diulang
cat << 'EOF' > update-docs.sh
#!/bin/bash
set -eu

SOURCE_DIR="docs"
OUTPUT_DIR="site"
STAGING_DIR=$(mktemp -d "./.site-build.XXXXXX")
trap 'rm -rf "$STAGING_DIR"' EXIT

source_files=()
while IFS= read -r -d '' file; do
  source_files+=("$file")
done < <(find "$SOURCE_DIR" -type f -name "*.md" -print0)
if [ "${#source_files[@]}" -eq 0 ]; then
  echo "Tidak ada sumber Markdown" >&2
  exit 1
fi

markdownlint "${source_files[@]}"

for file in "${source_files[@]}"; do
  relative_path=${file#"$SOURCE_DIR"/}
  output_file="$STAGING_DIR/${relative_path%.md}.html"
  mkdir -p "$(dirname "$output_file")"
  pandoc "$file" -o "$output_file" --standalone
done

[ ! -e "$OUTPUT_DIR" ] || rm -r -- "$OUTPUT_DIR"
mv "$STAGING_DIR" "$OUTPUT_DIR"
trap - EXIT
EOF

chmod +x update-docs.sh
./update-docs.sh

# Tinjau perubahan sumber sebelum commit
git diff --check
git diff -- docs

Contoh Proyek Nyata

Contoh terakhir membuat empat source file dan menggabungkannya menjadi $satu dokumen HTML mandiri$ . Setiap input path ditulis secara eksplisit. Build langsung gagal jika salah satu input file tidak ditemukan:

project-example.sh

# Setup project structure
mkdir ai-project-docs
cd ai-project-docs

# Membuat struktur direktori
mkdir -p docs/api docs/tutorials docs/guides scripts build

# Create main documentation files
cat << 'EOF' > docs/README.md
# AI Project Documentation

## Apa yang Dilakukan Alat Ini
Dokumentasi lengkap untuk proyek AI programming.

## Bagaimana Dokumen Disusun
- [API Reference](#api)
- [Tutorials](#tutorials)
- [User Guides](#guides)
EOF

# Membuat halaman yang dirujuk
cat << 'EOF' > docs/api/README.md
# Referensi API {#api}

Jelaskan setiap antarmuka publik dan sertakan satu contoh yang telah diverifikasi.
EOF

cat << 'EOF' > docs/tutorials/README.md
# Tutorial {#tutorials}

Pandu pembaca menyelesaikan satu tugas secara utuh.
EOF

cat << 'EOF' > docs/guides/README.md
# Panduan Pengguna {#guides}

Jelaskan alur kerja berulang beserta batas keamanannya.
EOF

# Create automated build script
cat << 'EOF' > scripts/build-docs.sh
#!/bin/bash
set -eu

mkdir -p build

pandoc   docs/README.md   docs/api/README.md   docs/tutorials/README.md   docs/guides/README.md   --standalone   --output build/index.html

echo "Documentation build completed!"
EOF

chmod +x scripts/build-docs.sh

# Run the build
./scripts/build-docs.sh

Markdown membuat struktur dokumen tetap mudah dibaca di version control. CLI dapat menjalankan validasi dan konversi berulang kali. Edit source file Markdown, lalu periksa command dan path. Buat ulang output dan tinjau perubahannya.