Mkdocs, samee dukumiinti mahadnaqa barnaamijkan furan ee furan

Maqaalka soo socda waxaan ku eegeynaa Mkdocs. Hadaad horumariso softiweer oo aad raadiso madal loo abuuro dukumiintiyo mid ka mid ah mashaariicdaada. Ama haddii aad ka shaqeyso shirkad u baahan inay u sameyso dokumenti gudaha ah shaqaalaha. Xitaa haddii aad tahay isticmaale horumarsan oo doonaya inuu keydiyo qoraalada qaarkood. MkDocs waa qalab ay tahay inaad isku daydo.

Sooftiweerkani waa soo-saare bog oo joogto ah oo loogu talagalay in lagu abuuro aalado dukumiinti ah Way fududahay, quruxsan in la fiiriyo, oo ay fududahay in la dejiyo lana geeyo. Ma yahay ku qoran Python iyo si fudud waxay kaa rabtaa inaad ku abuurto faylashaada qaab Markdown ah. Kadib, adoo adeegsanaya hal feyl oo qaabeynta YAML ah, waxaad soo saari kartaa degel degsan oo adiga kuu shaqeeya.

Marka xigta waxaan arki doonaa sida ay u fududahay helitaanka degel dukumiinti dhammaystiran adoo adeegsanaya MkDocs. Qaar kale oo badan ayaa jira matoorrada goobta la mid ah ma guurto ah, laakiin tan wuxuu leeyahay qaabeyn iyo hirgelinta tan ugu fudud.

Isticmaale caadi ah ayaa sidoo kale u adeegsan kara softiweerkan Abuur madal maxalli ah si aad wax uga qorto naftiisa ama wax kale oo la mid ah.

Ku rakib MkDocs

Ku rakib gudaha

Aan aragno rakibidda MkDocs waa wax fudud. Waan awoodnaa ku rakib adigoo isticmaalaya tuubbo. Kaliya waa inaad furtaa terminal (Ctrl + Alt + T) kuna qor:

pip install mkdocs

Ka dib rakibidda, galkaaga shaqada, ku orod amarka soo socda bilow bogga:

mkdocs new mkdocspro

Ka dibna si bilow inaad u adeegto orod:

cd mkdocspro

mkdocs serve

Markaas waad awoodaa u tag localhost: 8000 (ama cinwaankaaga IP / hostname oo leh dekedda 8000) si loo arko sida MkDocs u shaqeeyo.

Ku rakib serverkaaga nginx

Maaddaama ay tani tahay koronto-dhaliye site, looma baahna mashiinka gadaal loo isticmaalo sida PHP ama Python. Waxaad awoodi doontaa inaad ku hirgeliso mashruuca MkDocs server-kaaga (nginx, apache2) daqiiqad gudahood. Tusaale ahaan, waa tan nginx qaabeynta martigelinta dalwaddii:

server {
        server_name ejemplo.com;

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

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

Bedelida tusaale.com leh cinwaanka aad ku haysato server-kaaga. Sidoo kale waa inaad bedesho / var / www / mkdocspro / goobta iyadoo loo marayo dariiqa hoosaadka hoose ee bogga ee ku jira serverkaaga. Markaas waxaan kaliya haysannaa dib u bilow nginx iyadoo amarka soo socda:

sudo service nginx restart

Hadda waxaad u jiheysan kartaa tusaale ahaan.com oo aad u aragtaa inay shaqeyneyso.

Ku rakib mawduuc kale Mkdocs

Mawduuca Mkdocs ee caadiga ahi si gaar ah uma fiicna. Laakiin mid kale ayaad ku rakibi kartaa daqiiqad gudaheed. Tusaalaha rakibidda mawduuc kale, wuxuu noqon doonaa kuwan soo socda. Taas oo aan ku aadayno rakibi mawduuca maadada:

pip install mkdocs-material

Ka dib rakibidda, si aad u kiciso mawduuca, waa inaad tafatir faylkaaga mkdocs.yml oo ka dhig mid la mid ah sidan. Fursadaha qaar ayaa lagu dari karaa:

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'

Fursadaha waa iska cad yihiin. Laakiin halkan waxaa ku yaal sharaxyo qaar:

• repo_url: waa Kaydinta Git URL. Haddii aad qorsheyneyso inaad si toos ah Git ugu darto mashruucaaga MkDocs, waxaad u adeegsan kartaa doorashadan si aad ugu oggolaato dadka inay wax ka beddelaan bogagga ama fargeeto mashruuca.
• edit_uri: Kani waa boostada loogu talagalay tafatirka bogagga GitHub. Waad beddeli kartaa haddii aad isticmaaleyso GitLab ama GitBucket.
• google_analytics: Ma jiro guddi xakameeya MkDocs. Sidaa darteed, in la ogaado oo soo booqda boggaaga, waa inaad isticmaashaa Google Analytics. Doorashadan ayaa kuu oggolaan doonta inaad geliso lambarkaaga raadraaca si aad ugu xirto koontadaada websaydhka.
• Iskuday: Haddii aad rabto awood nidaamka faallooyinka Disqus bogga internetka, waxaad ku qori kartaa magacaaga gaaban halkan.
• mawduuc: magaca mawduuca aad rabto inaad isticmaasho. Waa inaad horey u rakibtaa, sidii aan ku soo qaadanay mawduuca maaddada. Kani wuxuu noqon doonaa magaca aan ku isticmaali doonno tusaalaha.

Eeg isbedelada mawduuca cusub

Kadib kaydinta faylka, ordi mkdocs waxay ku dhex dhisantahay galka mkdocsproject. Websaydhkaagu wuxuu qaadan doonaa muuqaalka iyo dareemka mawduuca Mawduuca:

Muhiim: hubi inaad had iyo jeer socodsiiso mkdocs dhiska wax ka beddel kasta kadib inaad ku sameyso faylasha. Haddii kale wax isbeddel ah ma arki doontid.

Way badan yihiin mawduucyada kale iyo xulashooyinka si aad uhesho barnaamijkan. Waxaad kala tashan kartaa iyaga dukumiintiyada rasmiga ah waxaa qoray MkDocs. Waa tan liiska fursadaha suurtogalka ah in aan isticmaali karno.