Unlimited Wordpress themes, plugins, graphics & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Workflow
Webdesign

Dokumentasi Cepat dan Mudah Menggunakan Markdown

by
Length:LongLanguages:

Indonesian (Bahasa Indonesia) translation by ⚡ Rova Rindrata (you can also view the original English article)

Jadi Anda telah membuat tema, template, atau aplikasi web yang mengagumkan. Sekarang untuk bagian yang membosankan; dokumentasi. Menulis konten tentu tidak akan bermasalah, kemungkinan besar akan membuat file bantuan yang akan menghabiskan waktu yang berharga. Markdown, sintaks format sederhana dan *benar-benar* sederhana bisa menyelesaikan semua itu untuk Anda.

Tentang Markdown

Dibuat oleh John Gruber, Markdown adalah sintaks format teks biasa yang menjadikan pembuatan elemen HTML dasar menjadi lebih mudah.

Alih-alih menggunakan tag HTML (yang, dikatakan, membutuhkan banyak waktu untuk menulisnya) tugas Markdown adalah menyingkirkan dari proses berpikir Anda, sehingga Anda dapat fokus pada konten. Karena sintaksnya sangat mendasar, mudah untuk menulis dan membaca markdown. Nantinya dalam tutorial ini, kita akan berjalan melalui langkah-langkah membuat dokumentasi tema menggunakan Markdown, jadi Anda akan melihat betapa ringan dan cepatnya!

Mengkonversi Markdown

Begitu Anda berhasil mengatasi penulisan Markdown, Anda memerlukan beberapa jenis aplikasi parsing untuk mengubah Markdown menjadi markup HTML.

Konverter Markdown asli dibuat di Perl, namun sejak saat itu banyak aplikasi (di beberapa platform) telah muncul. Mari kita lihat beberapa pilihan, baik online dan berjalan di sistem Anda sendiri.

Dingus (Online)

Dingus adalah aplikasi web yang dibuat oleh orang yang sama yang telah memperkenalkan Anda Markdown. Cukup copy dan paste kode Markdown Anda dari editor teks (atau masukkan di area teks) dan dengan satu klik tombol, kode HTML Anda (dan juga pratinjau) akan muncul. Tidak ada yang mewah, tapi cara mudah untuk mengubah markdown menjadi HTML.

Dingus

MarkdownPad (Windows)

MarkdownPad adalah aplikasi Windows yang hebat yang memungkinkan Anda membuat file Markdown dengan mudah (dan gratis!) Ini termasuk fitur-fitur hebat seperti pratinjau HTML instan, format yang mudah dengan pintasan keyboard, kustomisasi CSS, ekspor HTML dan bahkan mode "distraction free".

MarkdownPad

Mou (OS X)

Mou adalah aplikasi Mac yang bagus dan gratis yang memungkinkan Anda menulis Markdown secara sederhana dan indah. Memiliki fitur hebat seperti styling kustom, pintasan keyboard, HTML langsung, ekspor HTML (dengan styling CSS opsional), ekspor PDF, dukungan pendiktean, dan banyak lagi. Untuk tutorial ini, kita akan menggunakan Mou untuk membuat dokumentasi tema kita.

Mou

MarkdownNote (OS X & iOS)

MarkdownNote adalah aplikasi hebat lainnya untuk menulis Markdown, dan aplikasi iOS sangat cocok jika Anda ingin menulis Markdown saat dalam perjalanan. Sama seperti aplikasi lain yang kita bahas, ada beberapa fitur hebat, termasuk pratinjau HTML langsung, pintasan keyboard, dan sinkronisasi Dropbox.

MarkdownNote

Membuat Dokumentasi Tema

Sejauh ini, kita telah membahas apa itu Markdown dan melihat beberapa alat yang dapat Anda gunakan untuk menuliskan Markdown. Sekarang mari kita membuat beberapa dokumentasi tema untuk tema yang tidak ada, mencakup apa yang biasanya Anda sertakan dalam dokumentasi, sintaks Markdown dan praktik terbaik.

Sintaks Markdown

Selama langkah-langkah berikut kita akan melihat Markdown karena berlaku untuk kebutuhan kita. Untuk melihat lebih dalam pada sintaks Markdown, lihat Markdown: Seluk beluk pada Nettuts+.

Apa yang Harus Disertakan Sebuah File Dokumentasi?

Karena Anda sudah mengetahui seluk beluk dari tema/template/aplikasi web Anda, mungkin agak membosankan untuk membahas dasar-dasarnya. Tujuan dari file dokumentasi adalah untuk melayani sebagai panduan bagi pengguna dan pembeli lainnya. Seringkali, ada instalasi, penyesuaian, dan beberapa tweak yang melibatkan pengguna yang perlu diketahui - dan tugas Anda untuk mendidik mereka. Inilah yang mungkin ingin kita sertakan:

  • Informasi
    • Penulis
    • Tanggal Pembuatan
    • Versi
    • Info Kontak.
  • Struktur File
    • HTML
    • CSS
    • Javascript
  • Struktur File Individu
    • Struktur HTML
    • Struktur CSS
  • Gaya Kustom
  • File Tweak
    • CSS Tweak
    • Javascript Tweak
  • Kompatibilitas Browser
  • Changelog

Ingat, dokumentasi harus cukup sederhana bagi siapa saja yang memiliki pengetahuan dasar untuk mengerti, namun juga mencakup cara mengubah file penting. Misalnya, Anda tidak perlu menunjukkan bagaimana mengubah nilai CSS tertentu, namun Anda harus menunjukkan cara mengakses file-file ini.

Langkah 1: Menyiapkan File Markdown

Sekarang saatnya untuk hal-hal menyenangkan! Silakan buka editor Markdown Anda (saya akan menggunakan Mou untuk Mac). Buat header untuk file dokumentasi Anda:

Elemen heading dapat ditulis hanya dengan menambahkan satu sampai enam # di depan konten. Pada contoh di atas, kita menggunakan satu tanda # untuk membuat elemen h1 dengan teks 'Theme Documentation'. Jika Anda ingin membuat elemen h3, Anda akan menulis ###Heading 3.

Sekarang, mari buat aturan horisontal (<hr />) untuk memisahkan judul dari konten lainnya. Sekali lagi, dalam Markdown ini sangat sederhana:

Langkah 2: Informasi Tema

Bagian penting untuk ditambahkan dalam dokumentasi Anda adalah bagian informasi.

Mari kita lihat HTML yang setara dari kode di atas:

Hanya dengan melihat dua sumber yang berbeda, Anda bisa langsung melihat Markdown lebih intuitif untuk dipahami dan diciptakan. Alih-alih terus-menerus harus menambahkan < dan >, Markdown memungkinkan Anda untuk fokus pada konten. Untuk menekankan, tambahkan tanda bintang sebelum dan sesudah teks (misalnya *Emphasized Text*). Untuk memperjelas, tambahkan dua tanda bintang sebelum dan sesudah teks (misalnya **Emboldened Text**). Untuk menambahkan jeda baris, cukup tambahkan dua spasi pada titik yang Anda inginkan untuk memasukkan jeda baris.

Langkah 3: Menambahkan Daftar Isi

Sekarang mari tambahkan daftar konten ke dalam file Markdown kita:

Jika kita membuat ini di HTML, berikut adalah bagaimana tampilannya:

Alih-alih harus membuat ordered list dan daftar item terpisah, cukup tulis 1. First Element dan lanjutkan menambahkan item tambahan.

Langkah 4: Struktur HTML

Penting untuk membiarkan pengguna Anda tahu bagaimana file situs diletakkan. Karena kita membuat dokumentasi untuk sebuah tema, kita harus menjelaskan bagaimana kode HTML dari tema terstruktur. Kita bisa menjelaskannya dengan kode berikut:

Sederhana. Untuk membuat daftar isi kita, kita menggunakan ordered list. Pada bagian ini, kita menggunakan undordered list bersarang. Untuk membuat unordered list dalam Markdown, cukup tambahkan tanda bintang dan spasi sebelum teks (misalnya * Item 1). Untuk menyarangkan item daftar, cukup indent ke dalam dan buat item daftar lainnya.

Langkah 5: File CSS

Terutama dalam tema, dokumentasi CSS sangat penting. Sebaiknya memperjelas file-file CSS yang berbeda yang disertakan dalam tema, serta deskripsi singkat setiap file:

Pastikan untuk menggunakan judul untuk memisahkan bagian yang berbeda dari file dokumentasi. File dokumentasi yang ditata dengan baik akan menyebabkan lebih sedikit pengguna yang kebingungan!

Langkah 6: File Javascript

Jika tema Anda menyertakan file Javascript, ada baiknya untuk setidaknya menjelaskannya di dokumentasi:

Pastikan Anda bukan hanya mencantumkan, namun menjelaskan file-file tersebut dalam tema Anda. Ini akan mempermudah pengguna memahami isi setiap file, dan memutuskan apakah mereka ingin mengacaukannya atau tidak.

Langkah 7: File PSD

Meskipun ada bagian terpisah untuk template PSD di ThemeForest, banyak penulis memutuskan untuk menyertakan file PSD dengan template kode mereka untuk memungkinkan kebebasan pengguna membuat perubahan desain. Jika tema Anda menyertakan file PSD, mungkin ide bagus untuk menggambarkannya sama seperti yang telah kami lakukan dengan semua file lainnya:

Praktik terbaik untuk memberi nama file PSD Anda dengan jelas (mis., full-width-page.psd) dibandingkan dengan nama yang tidak jelas (misalnya template-003.psd). Dengan cara ini, pengguna bisa menemukan apa yang mereka butuhkan tanpa harus membuka setiap file.

Langkah 8: Gaya Tema

Kemungkinan besar, tema Anda akan mencakup pilihan skema warna yang dapat dipilih pengguna Anda. Jika demikian, pastikan bahwa Anda menjelaskan bagaimana hal ini dilakukan:

Pada contoh di atas, saya telah mencantumkan skema warna yang berbeda yang disertakan dalam tema dan menunjukkan bagaimana cara mengubahnya.

Langkah 9: Javascript Tweak

Jika kode Anda menyertakan file Javascript yang memiliki parameter penyesuaian (misalnya skrip slider), sebaiknya Anda menunjukkan pengguna cara memanipulasi nilai-nilai tersebut:

Kode di atas menguraikan bagaimana pengguna dapat mengubah nilai-nilai. Untuk memberi gaya kode, bungkus teks yang relevan di dalam tag <code>. Aplikasi seperti Mou menambahkan styling ke elemen-elemen ini di pratinjau langsung, dan Anda juga dapat mengekspor kode untuk menjaga styling. Kami akan berbicara sedikit tentang mengekspor dokumentasi Anda nanti.

Langkah 10: CSS Tweak

File CSS sangat sering disesuaikan oleh pengguna. Mereka pasti akan menganggapnya bermanfaat jika Anda menambahkan sebuah bagian ke dokumentasi yang menunjukkan bagaimana mengakses file CSS sehingga mereka dapat mengeditnya.

Sekarang pengguna memiliki akses ke file CSS, mereka dapat membuat perubahan yang mereka inginkan.

Langkah 11: Kompatibilitas Browser

Sebaiknya beri tahu pengguna tentang apa pun masalah kompatibilitas browser:

Jika Anda ingin memperluas bagian ini, Anda bisa menjelaskan fitur tema apa yang terdampak di browser tertentu.

Langkah 12: Menyelesaikan Dokumentasi

Untuk melengkapi dokumentasi kita, kita akan menambahkan sebuah bagian untuk memberi tahu pengguna cara menghubungi kita jika mereka memiliki pertanyaan lebih lanjut. Mari tambahkan sedikit kode ini:

Untuk menghubungkan e-mail dengan menggunakan markdown, cukup bungkus alamat e-mail Anda antara chevron (misalnya <email@tutsplus.com>).

Menambahkan link di Mardown cukup sederhana. <a href="http://tutsplus.com" alt="The World's Leading Tutorial Network">Tuts+ adalah hyperlink yang Anda inginkan muncul di HTML. Teks harus ditempatkan di dalam kurung persegi [Tuts+]. Segera setelah itu, Anda memiliki alamat situs web yang dibungkus di antara tanda kurung (mis. (http://www.tutsplus.com/)) dan teks alt ditempatkan dalam tanda petik ganda di dalam tanda kurung (mis. (http://www.tutsplus.com/ "The World's Leading Tutorial Network")).

Kode Markdown Akhir

Berikut adalah kode akhir Markdown kita untuk dokumentasi ini:

Mengekspor Dokumentasi

Setelah kita selesai membuat file dokumentasi, saatnya mengkonversi Markdown menjadi HTML atau file PDF. Saya akan menggunakan Mou untuk mengekspor dokumentasi saya, namun langkah-langkahnya bersifat umum dan berlaku untuk sebagian besar aplikasi.

Mou

Mengekspor ke HTML

Untuk mengekspor dokumentasi Anda ke HTML, cukup pilih File > Export > HTML. Namai file dokumentasi Anda dan centang/hapus centang pada 'Include CSS' tergantung apakah Anda ingin styling yang sama ditampilkan dalam aplikasi untuk diterapkan ke file HTML Anda. Mou tidak akan membuat file CSS yang terpisah, namun menambahkan styling ke file HTML. Mou juga membuat tag yang diperlukan seperti html, doctypehead, dll.

Mengekspor ke PDF

Jika Anda ingin mengekspor dokumentasi Anda ke PDF, pilih File > Export > PDF. Dalam kasus Mou, semua styling yang ditampilkan dalam pratinjau langsung HTML akan disertakan dalam file PDF.

Dan kita sudah selesai! Dokumentasi yang jelas dan mudah dibaca untuk klien, pelanggan dan kolega. Unduh file sumber untuk tutorial ini dan periksa file .md .html dan .pdf yang dihasilkan.

Ikhtisar Sintaks Markdown

Berikut adalah perbandingan singkat dari sintaks HTML dan Markdown yang kita bahas dalam tutorial ini

<h1>heading One</h1> #Heading One
<h2>Heading Two</h2> ##Heading Two
<h3>Heading Three</h3> ###Heading Three
<h4>Heading Four</h4> ####Heading Four
<h5>Heading Five</h5> #####Heading Five
<h6>Heading Six</h6> #######Heading Six
<hr /> ***
<em>Teks Ditekankan</em> *Teks Ditekankan*
<strong>Teks Dipertegas</strong> **Teks Dipertegas**
<ol><li>List Element</li></ol> 1. List Element
<ul><li>List Element</li></ul> * List Element
<code>Code</code> <code>Code</code>
<a href="mailto:email@tutsplus.com"> email@tutsplus.com</a> <email@tutsplus.com>
<a href="http://www.tutsplus.com/" alt="Description">Forum</a> [forum] (http://www.tutsplus.com/ "Description")

Sumber Daya Tambahan

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.