Students Save 30%! Learn & create with unlimited courses & creative assets Students Save 30%! Save Now
Advertisement
  1. Web Design
  2. Workflow
Webdesign

Dokumentasi Cepat dan Mudah Menggunakan Markdown

by
Length:LongLanguages:

Malay (Melayu) translation by Kaustina Nurul Ilmi (you can also view the original English article)

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

Mengenai Markdown

Dibuat oleh John Gruber, Markdown adalah sintaks pemformatan teks biasa yang menjadikan elemen HTML asas lebih mudah.

Alih-alih menggunakan tag HTML (yang, dikatakan, memerlukan banyak masa untuk menulisnya) Markdown tugas adalah mengusir dari pemikiran 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 berjaya mengatasi Penulisan Markdown, Anda memerlukan beberapa jenis parsing aplikasi untuk mengubah Markdown menjadi HTML markup.

Konverter Markdown asli dibuat di Perl, tetapi sejak itu banyak aplikasi (di beberapa platform) telah muncul. Mari kita lihat beberapa pilihan, baik dalam talian dan berjalan di sistem anda sendiri.

Dingus (Dalam Talian)

Dingus adalah aplikasi web yang dibuat oleh orang yang sama yang telah memperkenalkan Anda Markdown. Cukup salin dan tampal kod Markdown Anda dari teks editor (atau masukkan di teks kawasan) dan dengan satu klik tombol, kod HTML anda (dan juga preview) akan muncul. Tidak ada yang mewah, tetapi cara mudah untuk mengubah markdown menjadi HTML.

Dingus

MarkdownPad (Windows)

MarkdownPad adalah aplikasi Windows yang hebat yang membolehkan anda membuat file Markdown dengan mudah (dan percuma!) Ini termasuk ciri-ciri hebat seperti pratinjau HTML instan, mudah format dengan keyboard pintasan, CSS customization, ekspor HTML dan bahkan mode "bebas gangguan".

MarkdownPad

Mou (OS X)

Mou adalah aplikasi Mac yang bagus dan percuma yang membolehkan anda menulis Markdown secara sederhana dan indah. Mempunyai ciri hebat seperti styling kustom, keyboard pintasan, HTML langsung, ekspor HTML (dengan styling CSS opsional), export PDF, pendiktean sokongan, dan banyak lagi. Untuk tutorial ini, kita akan menggunakan Mou untuk membuat dokumentasi tema kita.

Mou

MarkdownNote (OS X & iOS)

MarkdownNote adalah aplikasi lain yang hebat untuk menulis Markdown, dan aplikasi iOS sangat sesuai jika anda ingin menulis Markdown semasa dalam perjalanan. Sama seperti aplikasi lain yang kami bahas, ada beberapa ciri hebat, termasuk langsung HTML pratinjau, keyboard pintasan, dan sinkronisasi Dropbox.

MarkdownNote

Membuat Dokumentasi Tema

Sejauh ini, kami telah membahas apa itu Markdown dan melihat beberapa alat yang boleh anda gunakan untuk menuliskan Markdown. Sekarang mari kita buat beberapa dokumentasi tema untuk tema yang tidak ada, termasuk apa yang biasanya anda sertakan dalam dokumentasi, sintaks Markdown dan best practices.

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 perlu disertakan Dokumentasi Fail?

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

  • Maklumat
    • Penulis
    • Tarikh Pembuatan
    • Versi
    • Maklumat Kenalan.
  • Fail Struktur
    • HTML
    • CSS
    • Javascript
  • Fail Struktur Individu
    • Struktur HTML
    • Struktur CSS
  • Gaya Kustom
  • Tweak fail
    • CSS Tweak
    • Javascript Tweak
  • Pelayar Kompatibilitas
  • Changelog

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

Langkah 1: Menyediakan Pemadaman Fail

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

Tajuk Elemen boleh ditulis hanya dengan menambah satu hingga enam # di depan kandungan. Pada contoh di atas, kami menggunakan satu tanda # untuk membuat h1 elemen dengan teks 'Documentation Theme'. Jika anda ingin membuat elemen h3 , anda akan menulis ###Heading 3 .

Sekarang, mari buat peraturan horisontal ( hr /> ) untuk memisahkan tajuk dari lain-lain kandungan. Sekali lagi, dalam Markdown ini sangat sederhana:

Langkah 2: Maklumat Tema

Bahagian penting untuk ditambah dalam dokumentasi anda adalah bahagian maklumat.

Mari kita lihat HTML setara dari kod di atas:

Hanya dengan melihat dua sumber yang berbeza, anda dapat melihat Markdown lebih intuitif untuk dimengerti dan diciptakan. Alih-alih terus-menerus perlu menambah < dan > , Markdown membolehkan anda untuk fokus pada kandungan. Untuk menekankan, tambah tanda bintang sebelum dan sesudah teks (contohnya *Emphasized Text* Diperkasakan *Emphasized Text* ) Untuk memperjelas, tambahkan dua tanda bintang sebelum dan sesudah teks (misalnya **Emboldened Text** ). Untuk menambah jeda baris, cukup tambah dua spasi pada titik yang anda inginkan untuk memasukkan jeda baris.

Langkah 3: Menambah Isi Daftar

Sekarang mari tambahkan senarai kandungan ke dalam file Markdown kita:

Jika kita membuat ini di HTML, berikut ialah bagaimana rupa:

Alih-alih harus membuat senarai pesanan dan daftar item berasingan, cukup tulis 1. First Element dan lanjutkan menambah tambahan item.

Langkah 4: Struktur HTML

Penting untuk membolehkan pengguna mengetahui bagaimana tapak web diletakkan. Karena kita membuat dokumentasi untuk tema, kita harus menjelaskan bagaimana kode HTML dari tema terstruktur. Kita boleh menjelaskannya dengan kod berikut:

Sederhana. Untuk membuat senarai isi kami, kami menggunakan senarai pesanan.Pada bahagian ini, kita menggunakan senarai tanpa urutan yang bersaran. Untuk membuat senarai tidak teratur dalam Markdown, cukup tambah tanda bintang dan spasi sebelum teks (misalnya * Item 1 ). Untuk menyarangkan senarai item, cukup indent ke dalam dan buat item daftar lain.

Langkah 5: Fail CSS

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

Pastikan untuk menggunakan tajuk untuk memisahkan bahagian yang berbeza dari dokumentasi file. Fail dokumentasi yang ditata dengan baik akan menyebabkan lebih sedikit pengguna yang kebingungan!

Langkah 6: Fail Javascript

Jika tema anda menyertakan Javascript fail, ada baiknya untuk sekurang-kurangnya menerangkannya di dokumentasi:

Pastikan anda bukan hanya mencantumkan, tetapi menjelaskan file-file tersebut dalam tema anda. Ini akan mempermudah pengguna memahami kandungan setiap fail, dan memutuskan apakah mereka mahu mengacaukannya atau tidak.

Langkah 7: Fail JPA

Walaupun terdapat bahagian terpisah untuk PSD template di WorldWideThemes.net , banyak penulis memutuskan untuk menyertakan PSD file dengan template mereka untuk memungkinkan pengguna bebas membuat perubahan desain. Jika tema anda menyertakan JPA fail, mungkin ide bagus untuk menggambarkannya sama seperti yang telah kami lakukan dengan semua file lainnya:

Praktik terbaik untuk memberikan nama PSD nama anda dengan jelas (mis., Full-width-page.psd) berbanding dengan nama yang tidak jelas (misalnya template-003.psd). Dengan cara ini, pengguna dapat mengetahui apa yang mereka perlukan tanpa perlu membuka setiap fail.

Langkah 8: Gaya Tema

Kemungkinan besar, tema anda akan menyertakan pilihan warna skema yang dapat dipilih oleh pengguna anda. Jika demikian, pastikan bahawa anda menjelaskan bagaimana hal ini dilakukan:

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

Langkah 9: Javascript Tweak

Jika kod anda menyertakan Javascript file yang memiliki parameter penyesuaian (misal skrip slider), sebaiknya Anda menunjukkan pengguna cara memanipulasi nilai-nilai itu:

Kod di atas menguraikan bagaimana pengguna boleh mengubah nilai-nilai. Untuk memberikan kod gaya, bungkus teks yang relevan di dalamcode tag <code>. Aplikasi seperti Mou menambah styling ke elemen-elemen ini di pratinjau langsung, dan Anda juga dapat mengekspor kod untuk menjaga gaya. Kami akan bercakap sedikit tentang mengekspor dokumentasi anda nanti.

Langkah 10: CSS Tweak

Fail CSS sangat sering disesuaikan oleh pengguna. Mereka pasti akan menganggapnya bermanfaat jika anda menambah satu bagian ke dokumentasi yang menunjukkan bagaimana mengakses CSS file sehingga mereka dapat mengeditnya.

Kini pengguna mempunyai akses ke CSS fail, mereka boleh membuat perubahan yang mereka inginkan.

Langkah 11: Pelayar Kompatibiliti

Sebaiknya beri tahu pengguna mengenai apa pun masalah kompatibilitas browser:

Jika anda ingin memperluas bahagian ini, Anda dapat menjelaskan fitur tema apa yang terkampak di peramban tertentu.

Langkah 12: Menyelesaikan Dokumentasi

Untuk melengkapi dokumentasi kami, kami akan menambahkan bahagian untuk memberi tahu pengguna cara menghubungi kami jika mereka mempunyai pertanyaan lebih lanjut. Mari tambahkan sedikit kod ini:

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

Menambah link di Mardown cukup sederhana. ,a href="http://tutsplus.com"alt="The World's Leading Tutuorial Network">Tuts+ adalah hiperpautan yang anda inginkan muncul di HTML. Teks harus ditempatkan di dalam kurung persegi Tuts+. Segera selepas itu, anda mempunyai alamat web yang dibungkus di antara tanda kurung (mis.(http://www.tutsplus.com/) ) dan alt teks ditempatkan dalam tanda petik ganda di tanda kurung (mis.(http://www.tutsplus.com/ "The World's Leading Tutorial Network")).

Akhir Penutupan Kod

Berikut adalah markdown akhir kami untuk dokumentasi ini:

Mengekspor Dokumentasi

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

Mou

Mengekspor ke HTML

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

Mengekspor ke PDF

Sekiranya anda ingin mengekspor dokumentasi anda ke PDF, pilih File> Export> PDF . Dalam kes Mou, semua gaya yang dipaparkan dalam pratinjau HTML langsung akan disertakan dalam PDF file.

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

Ikhtisar Sintaks Markdown

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

<h1>heading One</h1> #Heading One
<h2>Heading Two</h2> ## Tajuk Kedua
<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>Emboldened Text</strong> **Teks yang dibangkitkan**
<ol><li>List Element</li></ol> 1. Elemen Senarai
<ul><li>List Element</li></ul> * Senarai Unsur
<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 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.