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:
pip install mkdocs
Efter installation i din arbejdsmappe skal du køre følgende kommando til initialiser et websted:
mkdocs new mkdocspro
Og så til begynde at servere det løb:
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.
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:
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.
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
Hilsen. Vous pouvez éventuellement trouver une solution à votre demande dans la dokumentation du projet. Les hilsner.