AmaMkdocs, dala imibhalo ngenxa yale software yomthombo ovulekile

Esihlokweni esilandelayo sizobheka amaMkdocs. Uma wenza isoftware futhi ufune ipulatifomu yokwakha imibhalo ngomunye wamaphrojekthi wakho. Noma uma usebenza enkampanini edinga ukudala imibhalo yangaphakathi yabasebenzi. Noma ngabe ungumsebenzisi othuthukile ofuna ukusindisa amanye amanothi. IMkDocs ithuluzi okufanele ulizame.

Le software iyi-static site generator ehlose ukudala amapulatifomu emibhalo. Ilula kakhulu, ibukeka kahle, futhi kulula ukuyisetha nokuyithumela. Ingabe ibhalwe nge-python futhi kalula kudinga ukuthi udale amafayela akho ngefomethi ye-Markdown. Ngemuva kwalokho, usebenzisa ifayili elilodwa lokumiswa kwe-YAML, ungakhiqiza iwebhusayithi emile ekusebenzela.

Okulandelayo sizobona ukuthi kulula kanjani ukuthola iwebhusayithi ephelele yemibhalo usebenzisa ama-MkDocs. Kunabanye abaningi ama-generator esayithi static efanayo, kepha lokhu inokucushwa nokuqaliswa kokulula.

Umsebenzisi ojwayelekile angasebenzisa le software ukwenza dala ipulatifomu yendawo ukubhala amanothi yena noma enye into efana nayo.

Faka ama-MkDocs

Faka endaweni

Ake sibone ukuthi ukufaka i-MkDocs kulula kakhulu. Sizokwazi ifake usebenzisa ipayipi. Kufanele uvule ukuphela (Ctrl + Alt + T) bese ubhala kuwo:

pip install mkdocs

Ngemuva kokufakwa, enkombeni yakho yokusebenza, sebenzisa umyalo olandelayo ku qala isiza:

mkdocs new mkdocspro

Bese kuthi ku qala ukuyiphaka sebenzisa:

cd mkdocspro

mkdocs serve

Ngemuva kwalokho unga iya ku-localhost: 8000 (noma ikheli lakho le-IP / igama lomethuleli nge-port 8000) ukubona ukuthi iMkDocs isebenza kanjani.

Faka kuseva yakho ye-nginx

Njengoba lokhu kungumenzi wesayithi emile, ayikho injini yokubuyela emuva edingekayo njenge-PHP noma iPython. Uzokwazi ukusebenzisa iphrojekthi ye-MkDocs kuseva yakho yewebhu (nginx, apache2) ngomzuzu. Isibonelo, nansi ifayili le- ukumiswa kokubamba kwe-nginx:

server {
        server_name ejemplo.com;

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

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

Esikhundleni example.com ngesizinda onaso kuseva yakho. Kuzofanele futhi ushintshe / var / www / mkdocspro / site ngendlela yefolda engaphansi yesiza kuseva yakho. Ngemuva kwalokho sinakho kuphela qala kabusha i-nginx ngomyalo olandelayo:

sudo service nginx restart

Manje usungangena ku- example.com bese uyibona isebenza.

Faka enye itimu kumaMkdocs

Itimu ezenzakalelayo yeMkdocs ayiyinhle ngokukhethekile. Kepha ungafaka enye ngomzuzu. Isibonelo sokufakwa kwenye indikimba, kuzoba okulandelayo. Esizokwenza ngayo faka ingqikithi yezinto ezibonakalayo:

pip install mkdocs-material

Ngemuva kokufakwa, ukwenza kusebenze ingqikithi, kuzofanela hlela ifayela lakho le-mkdocs.yml bese ulenza lifane nalokhu. Ezinye izinketho zingangezwa:

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'

Izinketho zicacile. Kepha nazi izincazelo:

• i-repo_url: yi I-URL yokugcina izinto zeGit. Uma uhlela ukuhlanganisa iGit ngqo kuphrojekthi yakho ye-MkDocs, ungasebenzisa le nketho ukuvumela abantu ukuthi bahlele amakhasi noma baphambukele iphrojekthi.
• hlela_uri: Lona postfix yokuhlela amakhasi ku-GitHub. Ungayiguqula uma usebenzisa iGitLab noma iGitBucket.
• google_analytics: Alikho iphaneli yokulawula ye-MkDocs. Ngakho-ke, ukwazi ovakashela iwebhusayithi yakho, kufanele usebenzise iGoogle Analytics. Le nketho izokuvumela ukuthi ufake inombolo yakho yokulandelela ukuhlobanisa i-akhawunti yakho newebhusayithi.
• ungaqedi: Uma ufuna vumela uhlelo lokubeka amazwana lwe-Disqus kuwebhusayithi, ungafaka igama lakho elifushane lapha.
• isihloko: The igama lengqikithi ofuna ukuyisebenzisa. Kuzofanele uyifake ngaphambili, njengoba senze nje ngengqikithi yezinto ezibonakalayo. Leli kuzoba igama esizolisebenzisa esibonelweni.

Bona ushintsho lwetimu entsha

Ngemuva kokugcina ifayili, run mkdocs build ngaphakathi kwefolda mkdocsproject. Iwebhusayithi yakho izokwamukela ukubukeka nokuzenzakalelayo kwetimu Yento:

Okubalulekile: qiniseka ukuthi uhlala usebenzisa ama-mkdocs build ngemuva kwakho konke ukuguqulwa okwenzayo kumafayela. Ngaphandle kwalokho ngeke ubone ushintsho.

Kukhona eziningi ezinye izingqikithi nezinketho ukumisa le software. Ungabonisana nabo ku imibhalo esemthethweni ngu-MkDocs. Nalu uhlu lwe izinketho ezingenzeka esingazisebenzisa.