Mkdocs, opret dokumentation takket være denne open source-software

om mkdocs

I den næste artikel skal vi se på Mkdocs. Hvis du udvikler software og søger en platform til oprettelse af dokumentation til et af dine projekter. Eller hvis du arbejder i en virksomhed, der har brug for at oprette intern dokumentation til personalet. Selvom du er en avanceret bruger, der ønsker at gemme nogle noter. MkDocs er et værktøj, du skal prøve.

Denne software er en statisk stedgenerator, der har til formål at skabe dokumentationsplatforme. Det er ret simpelt, smukt at se på og let at konfigurere og implementere. Er skrevet på python og simpelthen kræver, at du opretter dine filer i Markdown-format. Derefter kan du ved hjælp af en enkelt YAML-konfigurationsfil generere et statisk websted, der fungerer for dig.

Dernæst vil vi se, hvor let det er at få et komplet dokumentationswebsted ved hjælp af MkDocs. Der er mange andre webstedsgeneratorer lignende statisk, men dette har en konfiguration og implementering af det enkleste.

En normal bruger kunne også bruge denne software til oprette en lokal platform til at tage noter for sig selv eller noget andet lignende.

Installer MkDocs

Installer lokalt

Lad os se, at installation af MkDocs er ret let. Vi kan installer det ved hjælp af pip. Du skal bare åbne en terminal (Ctrl + Alt + T) og skrive i den:

Installation af mkdocs med PIP

pip install mkdocs

Efter installation i din arbejdsmappe skal du køre følgende kommando til initialiser et websted:

mkdocs lancerer projekt

mkdocs new mkdocspro

Og så til begynde at servere det løb:

server mkdocs

cd mkdocspro

mkdocs serve

Så kan du gå til localhost: 8000 (eller din IP-adresse / værtsnavn med port 8000) for at se, hvordan MkDocs fungerer.

mkdovs set fra browseren

Installer på din nginx-server

Da dette er en statisk generator, ingen backend-motor nødvendig som PHP eller Python. Du vil være i stand til at implementere MkDocs-projektet på din webserver (nginx, apache2) på et minut. For eksempel er her nginx virtuel værtskonfiguration:

server {
        server_name ejemplo.com;

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

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

Erstatter eksempel.com med det domæne, du har på din server. Du bliver også nødt til at ændre / var / www / mkdocspro / site ved stien til undermappen på webstedet på din server. Så har vi kun genstart nginx med følgende kommando:

sudo service nginx restart

Nu kan du gå over til example.com og se det arbejde.

Installer et andet tema i Mkdocs

Standard Mkdocs-temaet er ikke særlig godt. Men du kan installere en anden på et minut. Et eksempel på installation af et andet tema vil være følgende. Med hvilken vi skal installer materialetema:

pip install mkdocs-material

Efter installationen skal du gøre det for at aktivere temaet rediger din mkdocs.yml-fil og få den til at ligne den. Nogle muligheder kan tilføjes:

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'

Indstillingerne er helt klare. Men her er nogle forklaringer:

  • repo_url: er Git-lager-URL. Hvis du planlægger at integrere Git direkte i dit MkDocs-projekt, kan du bruge denne mulighed til at lade folk redigere siderne eller forkaste projektet.
  • edit_uri: Dette er postfix til redigering af sider på GitHub. Du kan ændre det, hvis du bruger GitLab eller GitBucket.
  • google_analytics: Der er intet kontrolpanel til MkDocs. Derfor at vide som besøger dit websted, skal du bruge Google Analytics. Denne mulighed giver dig mulighed for at indsætte dit sporingsnummer for at knytte din konto til webstedet.
  • Disqus: Hvis du vil aktiver Disqus-kommentarsystem på hjemmesiden kan du indsætte dit korte navn her.
  • tema: Den navnet på det tema, du vil bruge. Du bliver nødt til at installere det tidligere, som vi netop gjorde med materialetemaet. Dette vil være det navn, som vi vil bruge i eksemplet.

Se ændringerne af det nye tema

Efter at have gemt filen, kør mkdocs build inde i mkdocsproject-mappen. Dit websted vil anvende standardudseendet og følelsen af ​​temaet Materiale:

mkdocs brugerdefineret tema

Vigtigt: Sørg for altid at køre mkdocs build efter hver ændring som du gør i filerne. Ellers vil du ikke se nogen ændring.

der er mange andre temaer og muligheder for at konfigurere denne software. Du kan konsultere dem i officiel dokumentation af MkDocs. Her er en liste over mulige muligheder som vi kan bruge.


2 kommentarer, lad dine

Efterlad din kommentar

Din e-mailadresse vil ikke blive offentliggjort. Obligatoriske felter er markeret med *

*

*

  1. Ansvarlig for dataene: Miguel Ángel Gatón
  2. Formålet med dataene: Control SPAM, management af kommentarer.
  3. Legitimering: Dit samtykke
  4. Kommunikation af dataene: Dataene vil ikke blive kommunikeret til tredjemand, undtagen ved juridisk forpligtelse.
  5. Datalagring: Database hostet af Occentus Networks (EU)
  6. Rettigheder: Du kan til enhver tid begrænse, gendanne og slette dine oplysninger.

  1.   michael sagde han

    Hej
    Quand je fait un mkdocs build pour générer mon site, dossierwebstedet er oprettet med et index.html et quand je vais sur mon url j'ai http://mon_site/site.

    Og en t'il moyen de réécrire da http://mon_site/site en http://mon_site ?

    CDT

    1.    Damien A. sagde han

      Hilsen. Vous pouvez éventuellement trouver une solution à votre demande dans la dokumentation du projet. Les hilsner.