Mkdocs, buat dokumentasi berkat perangkat lunak sumber terbuka ini

Pada artikel selanjutnya kita akan melihat Mkdocs. Jika Anda mengembangkan perangkat lunak dan mencari sebuah platform untuk membuat dokumentasi untuk salah satu proyek Anda. Atau jika Anda bekerja di perusahaan yang perlu membuat dokumentasi internal untuk staf. Bahkan jika Anda adalah pengguna mahir yang ingin menyimpan beberapa catatan. MkDocs adalah alat yang harus Anda coba.

Perangkat lunak ini adalah generator situs statis yang bertujuan membuat platform dokumentasi. Ini cukup sederhana, cantik untuk dilihat, dan mudah disiapkan dan diterapkan. Aku s ditulis dengan python dan sederhana mengharuskan Anda untuk membuat file Anda dalam format penurunan harga. Kemudian, dengan menggunakan satu file konfigurasi YAML, Anda dapat membuat situs web statis yang sesuai untuk Anda.

Selanjutnya kita akan melihat betapa mudahnya mendapatkan website dokumentasi yang lengkap menggunakan MkDocs. Masih banyak lagi lainnya generator situs statis serupa, tapi ini memiliki konfigurasi dan implementasi yang paling sederhana.

Pengguna biasa juga dapat menggunakan perangkat lunak ini untuk buat platform lokal untuk membuat catatan untuk dirinya sendiri atau hal lain yang serupa.

Instal MkDocs

Instal secara lokal

Mari kita lihat bahwa menginstal MkDocs cukup mudah. Kita akan bisa instal menggunakan pip. Anda hanya perlu membuka terminal (Ctrl + Alt + T) dan menulis di dalamnya:

pip install mkdocs

Setelah penginstalan, di direktori kerja Anda, jalankan perintah berikut ke menginisialisasi situs:

mkdocs new mkdocspro

Dan kemudian mulai menyajikannya Lari:

cd mkdocspro

mkdocs serve

Maka kamu bisa pergi ke localhost: 8000 (atau alamat IP / nama host Anda dengan port 8000) untuk melihat cara kerja MkDocs.

Instal di server nginx Anda

Karena ini adalah generator situs statis, tidak diperlukan mesin backend seperti PHP atau Python. Anda akan dapat mengimplementasikan proyek MkDocs di server web Anda (nginx, apache2) dalam satu menit. Misalnya, ini konfigurasi host virtual nginx:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

Menggantikan example.com dengan domain yang Anda miliki di server Anda. Anda juga harus berubah / var / www / mkdocspro / situs melalui jalur subfolder situs di server Anda. Maka kita hanya punya mulai ulang nginx dengan perintah berikut:

sudo service nginx restart

Sekarang Anda dapat membuka example.com dan melihatnya berfungsi.

Instal tema lain di Mkdocs

Tema default Mkdocs tidak terlalu bagus. Tetapi Anda dapat menginstal yang lain dalam satu menit. Contoh pemasangan tema lain, adalah sebagai berikut. Dengan mana kita akan pergi pasang tema material:

pip install mkdocs-material

Setelah instalasi, untuk mengaktifkan tema, Anda harus melakukannya edit file mkdocs.yml Anda dan buat seperti ini. Beberapa opsi dapat ditambahkan:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

Opsinya cukup jelas. Namun berikut beberapa penjelasannya:

• repo_url: adalah URL repositori Git. Jika Anda berencana untuk mengintegrasikan Git secara langsung ke dalam proyek MkDocs Anda, Anda dapat menggunakan opsi ini untuk mengizinkan orang mengedit halaman atau garpu proyek.
• edit_uri: Ini adalah postfix untuk mengedit halaman di GitHub. Anda dapat mengubahnya jika Anda menggunakan GitLab atau GitBucket.
• google_analytics: Tidak ada panel kontrol untuk MkDocs. Oleh karena itu, untuk mengetahui yang mengunjungi situs web Anda, Anda harus menggunakan Google Analytics. Opsi ini memungkinkan Anda memasukkan nomor pelacakan untuk mengaitkan akun Anda dengan situs web.
• Disqus: Jika kamu mau aktifkan sistem komentar Disqus di situs web, Anda dapat memasukkan nama pendek Anda di sini.
• tema: The nama tema yang ingin Anda gunakan. Anda harus menginstalnya sebelumnya, seperti yang baru saja kita lakukan dengan tema material. Ini akan menjadi nama yang akan kita gunakan dalam contoh.

Lihat perubahan tema baru

Setelah menyimpan file tersebut, jalankan mkdocs build di dalam folder mkdocsproject. Situs web Anda akan mengadopsi tampilan dan nuansa default dari tema Material:

Penting: pastikan untuk selalu menjalankan mkdocs build setelah setiap modifikasi yang Anda lakukan di file. Jika tidak, Anda tidak akan melihat perubahan apa pun.

Ada banyak tema dan pilihan lain untuk mengkonfigurasi perangkat lunak ini. Anda dapat berkonsultasi dengan mereka di dokumentasi resmi oleh MkDocs. Berikut adalah daftarnya opsi yang memungkinkan yang bisa kita gunakan.