Mkdocs, creați documentație datorită acestui software open source

În articolul următor vom analiza Mkdocs. Dacă dezvolți software și cauți o platformă pentru crearea documentației pentru unul dintre proiectele tale. Sau dacă lucrați într-o companie care trebuie să creeze documentație internă pentru personal. Chiar dacă sunteți un utilizator avansat care dorește să salveze câteva note. MkDocs este un instrument pe care ar trebui să-l încercați.

Acest software este un generator de site static care vizează crearea platformelor de documentare. Este destul de simplu, destul de uitat și ușor de configurat și implementat. Este scris în piton y simplu necesită să vă creați fișierele în format Markdown. Apoi, utilizând un singur fișier de configurare YAML, puteți genera un site web static care funcționează pentru dvs.

În continuare vom vedea cât de ușor este să obțineți un site de documentație complet utilizând MkDocs. Există multe altele generatoare de site-uri static similar, dar asta are o configurare și implementare dintre cele mai simple.

Un utilizator normal ar putea folosi acest software pentru creați o platformă locală pentru a lua notițe pentru sine sau orice altceva similar.

Instalați MkDocs

Instalați local

Să vedem că instalarea MkDocs este destul de ușoară. Vom putea instalați-l folosind pip. Trebuie doar să deschideți un terminal (Ctrl + Alt + T) și să scrieți în el:

pip install mkdocs

După instalare, în directorul dvs. de lucru, executați următoarea comandă la inițializați un site:

mkdocs new mkdocspro

Și apoi la începe să-l servească alerga:

cd mkdocspro

mkdocs serve

Atunci poti accesați localhost: 8000 (sau adresa dvs. IP / numele gazdei cu portul 8000) pentru a vedea cum funcționează MkDocs.

Instalați pe serverul dvs. nginx

Deoarece acesta este un generator de site static, nu este nevoie de niciun motor de backend, cum ar fi PHP sau Python. Veți putea implementa proiectul MkDocs pe serverul dvs. web (nginx, apache2) într-un minut. De exemplu, aici este configurația gazdei virtuale nginx:

server {
        server_name ejemplo.com;

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

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

Înlocuiește example.com cu domeniul pe care îl aveți pe serverul dvs. De asemenea, va trebui să vă schimbați / var / www / mkdocspro / site de calea subfolderului site-ului de pe serverul dvs. Atunci nu avem decât reporniți nginx cu următoarea comandă:

sudo service nginx restart

Acum puteți accesa example.com și puteți vedea cum funcționează.

Instalați o altă temă în Mkdocs

Tema implicită Mkdocs nu este deosebit de bună. Dar puteți instala încă unul într-un minut. Un exemplu de instalare a unei alte teme va fi următorul. Cu care mergem instalați tema materialului:

pip install mkdocs-material

După instalare, pentru a activa tema, va trebui editați fișierul mkdocs.yml și faceți-l similar cu acesta. Se pot adăuga câteva opțiuni:

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'

Opțiunile sunt destul de clare. Iată însă câteva explicații:

• repo_url: este Adresa URL a depozitului Git. Dacă intenționați să integrați Git direct în proiectul dvs. MkDocs, puteți utiliza această opțiune pentru a permite oamenilor să editeze paginile sau să proiecteze proiectul.
• edit_uri: Acesta este postfix pentru editarea paginilor pe GitHub. Puteți să o modificați dacă utilizați GitLab sau GitBucket.
• google_analytics: Nu există panou de control pentru MkDocs. Prin urmare, să știi care vă vizitează site-ul web, trebuie să utilizați Google Analytics. Această opțiune vă va permite să introduceți numărul de urmărire pentru a vă asocia contul cu site-ul web.
• Disqus: Daca vrei activați sistemul de comentarii Disqus pe site, puteți introduce numele scurt aici.
• temă: numele temei pe care doriți să o utilizați. Va trebui să îl instalați anterior, așa cum tocmai am făcut-o cu tema materială. Acesta va fi numele pe care îl vom folosi în exemplu.

Vedeți modificările noii teme

După salvarea fișierului, rulați mkdocs build în folderul mkdocsproject. Site-ul dvs. web va adopta aspectul implicit al temei Material:

Important: asigurați-vă că rulați întotdeauna mkdocs build după fiecare modificare pe care îl faceți în fișiere. Altfel nu veți vedea nicio modificare.

Sunt mulți alte teme și opțiuni pentru a configura acest software. Le puteți consulta în documentație oficială de MkDocs. Iată o listă de opțiuni posibile pe care le putem folosi.