Mkdocs, maak documentatie dankzij deze open source software

In het volgende artikel gaan we Mkdocs bekijken. Als u software ontwikkelt en zoekt een platform voor het maken van documentatie voor een van uw projecten. Of als u in een bedrijf werkt dat interne documentatie voor het personeel moet creëren. Zelfs als u een gevorderde gebruiker bent die enkele notities wil bewaren. MkDocs is een tool die u zou moeten proberen.

Deze software is een statische sitegenerator die gericht is op het maken van documentatieplatforms. Het is vrij eenvoudig, mooi om naar te kijken en gemakkelijk in te stellen en te implementeren. Is geschreven in python en eenvoudig vereist dat u uw bestanden in Markdown-indeling maakt​ Vervolgens kunt u met behulp van een enkel YAML-configuratiebestand een statische website genereren die voor u werkt.

Vervolgens zullen we zien hoe gemakkelijk het is om een ​​complete documentatiewebsite te verkrijgen met MkDocs. Er zijn er nog veel meer site generatoren soortgelijke statisch, maar dit heeft een configuratie en implementatie van de eenvoudigste.

Een normale gebruiker zou deze software ook kunnen gebruiken creëer een lokaal platform om aantekeningen te maken voor zichzelf of iets anders vergelijkbaars.

Installeer MkDocs

Installeer lokaal

Laten we eens kijken dat het installeren van MkDocs vrij eenvoudig is. We zullen kunnen installeer het met pip​ U hoeft alleen maar een terminal te openen (Ctrl + Alt + T) en erin te schrijven:

pip install mkdocs

Voer na de installatie in uw werkmap het volgende commando uit naar initialiseer een site:

mkdocs new mkdocspro

En dan voor begin het te serveren rennen:

cd mkdocspro

mkdocs serve

Dan kunt u ga naar localhost: 8000 (of uw IP-adres / hostnaam met poort 8000) om te zien hoe MkDocs werkt.

Installeer op uw nginx-server

Aangezien dit een statische sitegenerator is, geen backend-engine nodig zoals PHP of Python​ U kunt het MkDocs-project binnen een minuut op uw webserver (nginx, apache2) implementeren. Hier is bijvoorbeeld de nginx virtuele host-configuratie:

server {
        server_name ejemplo.com;

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

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

Vervangt example.com met het domein dat u op uw server heeft. Je zult ook moeten veranderen / var / www / mkdocspro / site door het pad van de submap van de site op uw server. Dan hebben we alleen herstart nginx met het volgende commando:

sudo service nginx restart

Nu kunt u naar example.com gaan en zien hoe het werkt.

Installeer een ander thema in Mkdocs

Het standaard Mkdocs-thema is niet bijzonder goed. Maar u kunt binnen een minuut een andere installeren. Een voorbeeld van installatie van een ander thema is het volgende. Waarmee we gaan installeer materiaal thema:

pip install mkdocs-material

Na installatie, om het thema te activeren, moet u bewerk je mkdocs.yml-bestand en maak het vergelijkbaar met dit​ Enkele opties kunnen worden toegevoegd:

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'

De opties zijn vrij duidelijk. Maar hier zijn enkele verklaringen:

• repo_url: is de Git-opslagplaats-URL​ Als je van plan bent om Git rechtstreeks in je MkDocs-project te integreren, kun je deze optie gebruiken om mensen toe te staan ​​de pagina's te bewerken of het project te splitsen.
• bewerk_uri: Dit is de postfix voor het bewerken van pagina's op GitHub​ U kunt het wijzigen als u GitLab of GitBucket gebruikt.
• google_analytics: Er is geen bedieningspaneel voor MkDocs. Daarom om te weten wie uw website bezoekt, moet u Google Analytics gebruiken​ Met deze optie kunt u uw trackingnummer invoeren om uw account aan de website te koppelen.
• Disqus: Als je wilt Schakel Disqus-reactiesysteem in op de website kunt u hier uw korte naam invoeren.
• thema: The naam van het thema dat u wilt gebruiken​ U moet het eerder installeren, zoals we net deden met het materiële thema. Dit is de naam die we in het voorbeeld zullen gebruiken.

Bekijk de veranderingen van het nieuwe thema

Na het opslaan van het bestand, voer mkdocs build uit in de map mkdocsproject​ Uw website krijgt de standaard look en feel van het thema Materiaal:

Belangrijk: zorg ervoor dat u altijd mkdocs build uitvoert na elke wijziging dat u doet in de bestanden. Anders zie je geen verandering.

er vele andere thema's en opties om deze software te configureren. U kunt ze raadplegen in het officiële documentatie door MkDocs. Hier is een lijst van mogelijke opties die we kunnen gebruiken.