Mkdocs, ƙirƙirar takaddun godiya ga wannan software ta buɗewa

A cikin labarin na gaba zamu kalli Mkdocs. Idan ka inganta software kuma ka nema dandamali don ƙirƙirar takardu ga ɗayan ayyukanku. Ko kuma idan kuna aiki a cikin kamfanin da ke buƙatar ƙirƙirar takaddun ciki don ma'aikata. Koda koda kai mai amfani ne wanda ke son adana wasu bayanan kula. MkDocs kayan aiki ne wanda yakamata ku gwada.

Wannan software ɗin wata janareta ce mai tsaka-tsakin yanar gizo da nufin ƙirƙirar dandamali na kayan aiki. Abu ne mai sauki, kyakkyawa don kallo, kuma mai sauƙin kafawa da turawa. Shin rubuta a Python kuma a sauƙaƙe yana buƙatar ka ƙirƙiri fayilolinka a cikin tsarin Markdown. Bayan haka, ta amfani da fayil ɗin daidaitawa na YAML guda ɗaya, zaku iya ƙirƙirar gidan yanar gizon tsaye wanda yake muku aiki.

Nan gaba zamu ga yadda yake da sauƙi don samun cikakken shafin yanar gizon amfani da MkDocs. Akwai wasu da yawa janareto kama da tsaye, amma wannan yana da tsari da aiwatar da mafi sauki.

Mai amfani na yau da kullun zai iya amfani da wannan software don ƙirƙirar dandamali na gida don ɗaukar bayanai don kansa ko wani abu makamancin haka.

Shigar da MkDocs

Shigar da gida

Bari mu ga cewa sanya MkDocs abu ne mai sauki. Za mu iya shigar da shi ta amfani da pip. Dole ne kawai ku buɗe tashar (Ctrl + Alt + T) ku rubuta a ciki:

pip install mkdocs

Bayan shigarwa, a cikin kundin adireshin aikinku, gudanar da wannan umarni zuwa fara shafin:

mkdocs new mkdocspro

Kuma a sa'an nan zuwa fara bauta masa gudu:

cd mkdocspro

mkdocs serve

Sannan zaka iya je zuwa localhost: 8000 (ko adireshin IP / sunan mai masauki tare da tashar jiragen ruwa 8000) don ganin yadda MkDocs ke aiki.

Shigar da sabar ku ta nginx

Tunda wannan janareta ne na yau da kullun, babu injin bayan bayanan da ake buƙata kamar PHP ko Python. Za ku iya aiwatar da aikin MkDocs a kan sabar yanar gizonku (nginx, apache2) a cikin minti daya. Misali, a nan ne nginx mai masaukin baki mai tsari:

server {
        server_name ejemplo.com;

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

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

Sauya misali.com tare da yankin da kake da shi a kan sabarka. Hakanan zaku canza / var / www / mkdocspro / shafin ta hanyar hanyar ƙaramar fayil ɗin shafin akan sabar ka. To muna da kawai sake kunnawa nginx tare da umarnin mai zuwa:

sudo service nginx restart

Yanzu zaku iya zuwa kan misali.com kuma ku ga yana aiki.

Sanya wani jigo a cikin Mkdocs

Tsoffin taken Mkdocs ba shi da kyau musamman. Amma zaka iya girka wani a cikin minti daya. Misali na shigar da wani jigo, zai zama mai zuwa. Tare da wacce zamu tafi shigar da kayan abu:

pip install mkdocs-material

Bayan shigarwa, don kunna taken, dole ne ku shirya fayilolin mkdocs.yml ɗinka kuma yi shi kama da wannan. Za'a iya ƙara wasu zaɓuɓɓuka:

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'

Zaɓuɓɓukan sun bayyana sarai. Amma ga wasu bayani:

• repo_url: shine URL na git. Idan kuna shirin haɗa Git kai tsaye cikin aikinku na MkDocs, zaku iya amfani da wannan zaɓin don bawa mutane damar shirya shafuka ko yatsan aikin.
• shirya_uri: Wannan shi ne postfix don gyara shafuka akan GitHub. Kuna iya canza shi idan kuna amfani da GitLab ko GitBucket.
• google_analytics: Babu kwamiti na kulawa don MkDocs. Saboda haka, don sani wanda ya ziyarci gidan yanar gizonku, dole ne ku yi amfani da Google Analytics. Wannan zaɓin zai ba ku damar saka lambar bin diddiginku don haɗa asusunku tare da gidan yanar gizon.
• disqus: Idan kana so kunna tsarin yin tsokaci na Disqus akan gidan yanar gizon, zaka iya saka gajeren sunan ka anan.
• Tema: A sunan taken da kake son amfani dashi. Dole ne ku girka shi a baya, kamar yadda muka yi kawai tare da jigon kayan. Wannan zai zama sunan da zamu yi amfani da shi a cikin misali.

Duba canje-canje na sabon taken

Bayan ajiye fayil din, gudanar da mkdocs a cikin babban fayil ɗin mkdocsproject. Gidan yanar gizonku zai ɗauki tsoho duba da jin taken taken:

Muhimmin: Tabbatar koyaushe gudanar mkdocs gina bayan kowane gyare-gyare cewa kayi a fayiloli. In ba haka ba ba za ku ga wani canji ba.

Akwai su da yawa wasu jigogi da zaɓuɓɓuka don saita wannan software. Kuna iya tuntuɓar su a cikin takaddun hukuma by Mazaje Ne Ga jerin yiwuwar zaɓuɓɓuka cewa za mu iya amfani da shi.