Mkdocs, lag dokumentasjon takket være denne programvaren med åpen kildekode

I neste artikkel skal vi ta en titt på Mkdocs. Hvis du utvikler programvare og søker en plattform for å lage dokumentasjon for et av prosjektene dine. Eller hvis du jobber i et selskap som trenger å lage intern dokumentasjon for personalet. Selv om du er en avansert bruker som vil lagre noen notater. MkDocs er et verktøy du bør prøve.

Denne programvaren er en statisk stedsgenerator som tar sikte på å lage dokumentasjonsplattformer. Det er ganske enkelt, pent å se på og enkelt å sette opp og distribuere. Er skrevet på python og rett og slett krever at du oppretter filene dine i Markdown-format. Deretter, ved hjelp av en enkelt YAML-konfigurasjonsfil, kan du generere et statisk nettsted som fungerer for deg.

Deretter vil vi se hvor enkelt det er å skaffe et komplett dokumentasjonsnettsted ved hjelp av MkDocs. Det er mange andre nettstedsgeneratorer lignende statisk, men dette har en konfigurasjon og implementering av det enkleste.

En vanlig bruker kan også bruke denne programvaren til å lage en lokal plattform for å ta notater for seg selv eller noe annet lignende.

Installer MkDocs

Installer lokalt

La oss se at installering av MkDocs er ganske enkelt. Vi kan installer den ved hjelp av pip. Du må bare åpne en terminal (Ctrl + Alt + T) og skrive i den:

pip install mkdocs

Etter installasjon, i arbeidskatalogen, kjører du følgende kommando til initialisere et nettsted:

mkdocs new mkdocspro

Og så til begynn å servere den løpe:

cd mkdocspro

mkdocs serve

Da kan du gå til localhost: 8000 (eller IP-adressen / vertsnavnet ditt med port 8000) for å se hvordan MkDocs fungerer.

Installer på nginx-serveren din

Siden dette er en statisk generator, ingen backend-motor nødvendig som PHP eller Python. Du vil kunne implementere MkDocs-prosjektet på webserveren din (nginx, apache2) på et minutt. For eksempel er her nginx virtuell vertkonfigurasjon:

server {
        server_name ejemplo.com;

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

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

Erstatter eksempel.com med domenet du har på serveren din. Du må også endre / var / www / mkdocspro / site ved banen til undermappen til nettstedet på serveren din. Da har vi bare start nginx på nytt med følgende kommando:

sudo service nginx restart

Nå kan du gå over til example.com og se at det fungerer.

Installer et annet tema i Mkdocs

Standard Mkdocs-tema er ikke spesielt bra. Men du kan installere en annen på et minutt. Et eksempel på installasjon av et annet tema vil være følgende. Som vi skal til installer materialtema:

pip install mkdocs-material

For å aktivere temaet må du etter installasjonen rediger mkdocs.yml-filen din og gjør den lik denne. Noen alternativer kan legges til:

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'

Alternativene er ganske klare. Men her er noen forklaringer:

• repo_url: er den URL for Git-depot. Hvis du planlegger å integrere Git direkte i MkDocs-prosjektet ditt, kan du bruke dette alternativet for å la folk redigere sidene eller forkaste prosjektet.
• edit_uri: Dette er postfix for redigering av sider på GitHub. Du kan endre det hvis du bruker GitLab eller GitBucket.
• Google Analytics: Det er ikke noe kontrollpanel for MkDocs. Derfor å vite som besøker nettstedet ditt, må du bruke Google Analytics. Dette alternativet lar deg sette inn sporingsnummeret ditt for å knytte kontoen din til nettstedet.
• Disqus: Hvis du vil aktiver Disqus kommentarsystem på nettstedet kan du sette inn ditt korte navn her.
• tema: The navnet på temaet du vil bruke. Du må installere den tidligere, som vi nettopp gjorde med materialtemaet. Dette vil være navnet vi vil bruke i eksemplet.

Se endringene i det nye temaet

Etter at du har lagret filen, kjør mkdocs build inne i mkdocsproject-mappen. Nettstedet ditt vil ta standard utseendet og følelsen av materialtemaet:

Viktig: sørg for å alltid kjøre mkdocs build etter hver endring som du gjør i filene. Ellers vil du ikke se noen endring.

Det er mange andre temaer og alternativer for å konfigurere denne programvaren. Du kan konsultere dem i offisiell dokumentasjon av MkDocs. Her er en liste over mulige alternativer som vi kan bruke.