Mga Mkdoc, lumikha ng dokumentasyon salamat sa bukas na mapagkukunang software na ito

Sa susunod na artikulo ay titingnan namin ang Mkdoc. Kung nagkakaroon ka ng software at naghahanap isang platform para sa paglikha ng dokumentasyon para sa isa sa iyong mga proyekto. O kung nagtatrabaho ka sa isang kumpanya na kailangang lumikha ng panloob na dokumentasyon para sa mga tauhan. Kahit na ikaw ay isang advanced na gumagamit na nais na makatipid ng ilang mga tala. Ang MkDoc ay isang tool na dapat mong subukan.

Ang software na ito ay isang static na generator ng site na naglalayong lumikha ng mga platform ng dokumentasyon. Ito ay medyo simple, medyo titingnan, at madaling i-set up at i-deploy. Ay nakasulat sa sawa at simple hinihiling sa iyo na likhain ang iyong mga file sa format na Markdown. Pagkatapos, gamit ang isang solong pagsasaayos ng YAML, maaari kang makabuo ng isang static na website na gagana para sa iyo.

Susunod makikita natin kung gaano kadali makakuha ng isang kumpletong website ng dokumentasyon gamit ang MkDocs. Maraming iba pa mga tagabuo ng site katulad ng static, ngunit ito ay may isang pagsasaayos at pagpapatupad ng pinakasimpleng.

Ang isang normal na gumagamit ay maaari ding gumamit ng software na ito upang lumikha ng isang lokal na platform upang kumuha ng mga tala para sa kanyang sarili o anumang bagay na katulad.

I-install ang MkDoc

Mag-install nang lokal

Tingnan natin na ang pag-install ng MkDocs ay medyo madali. Magagawa natin i-install ito gamit ang pip. Kailangan mo lamang buksan ang isang terminal (Ctrl + Alt + T) at isulat ito:

pip install mkdocs

Pagkatapos ng pag-install, sa iyong gumaganang direktoryo, patakbuhin ang sumusunod na utos sa magpasimula ng isang site:

mkdocs new mkdocspro

At pagkatapos ay sa simulang ihain ito tumakbo:

cd mkdocspro

mkdocs serve

Pagkatapos ay maaari mong pumunta sa localhost: 8000 (o ang iyong IP address / hostname na may port 8000) upang makita kung paano gumagana ang MkDocs.

I-install sa iyong server nginx

Dahil ito ay isang static na generator ng site, walang kailangan ng backend engine tulad ng PHP o Python. Magagawa mong ipatupad ang proyekto ng MkDoc sa iyong web server (nginx, apache2) sa isang minuto. Halimbawa, narito ang nginx virtual na pagsasaayos ng host:

server {
        server_name ejemplo.com;

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

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

Pinapalitan halimbawa.com kasama ang domain na mayroon ka sa iyong server. Kailangan mo ring magbago / var / www / mkdocspro / site sa pamamagitan ng landas ng subfolder ng site sa iyong server. Saka meron lang tayo restart nginx kasama ang sumusunod na utos:

sudo service nginx restart

Ngayon ay maaari kang magtungo sa halimbawa.com at makita itong gumana.

Mag-install ng isa pang tema sa Mkdoc

Ang default na tema ng Mkdoc ay hindi partikular na mahusay. Ngunit maaari kang mag-install ng isa pa sa isang minuto. Ang isang halimbawa ng pag-install ng isa pang tema, ay ang sumusunod. Sa kung saan pupunta kami i-install ang materyal na tema:

pip install mkdocs-material

Pagkatapos ng pag-install, upang buhayin ang tema, kakailanganin mong i-edit ang iyong mkdocs.yml file at gawin itong katulad nito. Ang ilang mga pagpipilian ay maaaring idagdag:

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'

Ang mga pagpipilian ay medyo malinaw. Ngunit narito ang ilang mga paliwanag:

• repo_url: ay ang Git repository URL. Kung balak mong isama ang Git nang direkta sa iyong proyekto sa MkDoc, maaari mong gamitin ang pagpipiliang ito upang payagan ang mga tao na i-edit ang mga pahina o tinidor ang proyekto.
• edit_uri: Ito ang postfix para sa pag-edit ng mga pahina sa GitHub. Maaari mo itong palitan kung gumagamit ka ng GitLab o GitBucket.
• google_analytics: Walang control panel para sa MkDocs. Samakatuwid, upang malaman na bumibisita sa iyong website, dapat mong gamitin ang Google Analytics. Papayagan ka ng pagpipiliang ito na ipasok ang iyong numero sa pagsubaybay upang maiugnay ang iyong account sa website.
• disqus: Kung gusto mo paganahin ang Disqus system ng pagkomento sa website, maaari mong ipasok ang iyong maikling pangalan dito.
• tema: Ang pangalan ng temang nais mong gamitin. Kailangan mong i-install ito dati, tulad ng ginawa namin sa materyal na tema. Ito ang magiging pangalan na gagamitin namin sa halimbawa.

Tingnan ang mga pagbabago ng bagong tema

Pagkatapos i-save ang file, patakbuhin ang mkdoc build sa loob ng mkdocsproject folder. Aangkin ng iyong website ang default na hitsura at pakiramdam ng tema ng Materyal:

Mahalaga: tiyaking palaging patakbuhin ang mkdoc build pagkatapos ng bawat pagbabago na gagawin mo sa mga file. Kung hindi, hindi ka makakakita ng anumang pagbabago.

Maraming iba pang mga tema at pagpipilian upang mai-configure ang software na ito. Maaari kang kumunsulta sa kanila sa opisyal na dokumentasyon ni MkDoc. Narito ang isang listahan ng mga posibleng pagpipilian na magagamit natin.