Mkdocs, ustvarite dokumentacijo zahvaljujoč tej odprtokodni programski opremi

V naslednjem članku si bomo ogledali Mkdocs. Če razvijate programsko opremo in iščete platforma za ustvarjanje dokumentacije za enega od vaših projektov. Ali če delate v podjetju, ki mora ustvariti interno dokumentacijo za osebje. Tudi če ste napreden uporabnik, ki želi shraniti nekaj zapiskov. MkDocs je orodje, ki ga morate preizkusiti.

Ta programska oprema je statični generator strani, namenjen ustvarjanju dokumentacijskih platform. Je precej preprost, lep na pogled in enostaven za namestitev in uvajanje. Je napisano v pythonu in preprosto zahteva, da ustvarite datoteke v formatu Markdown. Nato lahko z eno samo konfiguracijsko datoteko YAML ustvarite statično spletno mesto, ki ustreza vam.

Nato bomo videli, kako enostavno je dobiti celotno spletno mesto z dokumentacijo z uporabo MkDocs. Obstaja veliko drugih generatorji spletnih mest podoben statični, ampak to ima konfiguracijo in izvedbo najpreprostejšega.

Običajni uporabnik lahko to programsko opremo uporablja tudi za ustvarite lokalno platformo za zapisovanje zase ali kaj drugega podobnega.

Namestite MkDocs

Namestite lokalno

Poglejmo, da je namestitev MkDocs precej enostavna. Bomo lahko namestite ga s pomočjo pipa. Terminal morate preprosto odpreti (Ctrl + Alt + T) in vanj zapisati:

pip install mkdocs

Po namestitvi v delovnem imeniku zaženite naslednji ukaz za inicializirajte spletno mesto:

mkdocs new mkdocspro

In potem za začnite ga servirati teči:

cd mkdocspro

mkdocs serve

Potem lahko pojdite na localhost: 8000 (ali vaš naslov IP / ime gostitelja z vrati 8000), da vidite, kako deluje MkDocs.

Namestite na strežnik nginx

Ker gre za statični generator strani, noben stranski mehanizem, kot sta PHP ali Python, ni potreben. Projekt MkDocs boste lahko na svoji spletni strežnik (nginx, apache2) implementirali v minuti. Na primer, tukaj je konfiguracija navideznega gostitelja nginx:

server {
        server_name ejemplo.com;

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

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

Nadomešča example.com z domeno, ki jo imate na strežniku. Prav tako se boste morali spremeniti / var / www / mkdocspro / site po poti v podmapo spletnega mesta na vašem strežniku. Potem imamo samo znova zaženite nginx z naslednjim ukazom:

sudo service nginx restart

Zdaj se lahko obrnete na example.com in vidite, kako deluje.

Namestite drugo temo v Mkdocs

Privzeta tema Mkdocs ni posebej dobra. Lahko pa v minuti namestite še enega. Primer namestitve druge teme bo naslednji. S katerim se bomo namestite temo gradiva:

pip install mkdocs-material

Po namestitvi boste morali aktivirati temo uredite datoteko mkdocs.yml in jo naredite podobno tej. Dodati je mogoče nekaj možnosti:

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'

Možnosti so povsem jasne. Tu pa je nekaj razlag:

• repo_url: ali je URL skladišča Git. Če nameravate Git vključiti neposredno v svoj projekt MkDocs, lahko s to možnostjo omogočite ljudem, da urejajo strani ali razpršijo projekt.
• uredi_uri: To je postfix za urejanje strani na GitHub. Lahko ga spremenite, če uporabljate GitLab ali GitBucket.
• google_analytics: Za MkDocs ni nadzorne plošče. Zato vedeti ki obišče vaše spletno mesto, morate uporabljati Google Analytics. S to možnostjo lahko vstavite številko za sledenje, da svoj račun povežete s spletnim mestom.
• Disqus: Če želiš omogoči sistem komentiranja Disqus na spletni strani lahko tukaj vstavite svoje kratko ime.
• Tema: The ime teme, ki jo želite uporabiti. Morali ga boste predhodno namestiti, kot smo pravkar storili pri temi materiala. To bo ime, ki ga bomo uporabili v primeru.

Oglejte si spremembe nove teme

Po shranjevanju datoteke zaženite mkdocs build znotraj mape mkdocsproject. Vaše spletno mesto bo sprejelo privzeti videz in občutek teme Material:

Pomembno: poskrbite, da boste vedno izvajali mkdocs build po vsaki spremembi kar počnete v datotekah. V nasprotnem primeru ne boste videli sprememb.

Veliko jih je druge teme in možnosti za konfiguracijo te programske opreme. Z njimi se lahko posvetujete v uradna dokumentacija avtor MkDocs. Tu je seznam možne možnosti ki jih lahko uporabimo.