Mkdocs, twórz dokumentację dzięki temu oprogramowaniu open source

W następnym artykule przyjrzymy się Mkdocs. Jeśli tworzysz oprogramowanie i szukasz platforma do tworzenia dokumentacji dla jednego z twoich projektów. Lub jeśli pracujesz w firmie, która musi stworzyć wewnętrzną dokumentację dla pracowników. Nawet jeśli jesteś zaawansowanym użytkownikiem, który chce zapisać notatki. MkDocs to narzędzie, które powinieneś wypróbować.

To oprogramowanie jest statycznym generatorem witryn, którego celem jest tworzenie platform dokumentacji. Jest dość prosty, ładny i łatwy w konfiguracji i wdrożeniu. Jest napisane w Pythonie i po prostu wymaga utworzenia plików w formacie Markdown. Następnie, używając pojedynczego pliku konfiguracyjnego YAML, możesz wygenerować statyczną witrynę internetową, która działa dla Ciebie.

Następnie zobaczymy, jak łatwo jest uzyskać pełną dokumentację witryny internetowej za pomocą MkDocs. Jest wielu innych generatory witryn podobne zakłócenia, ale to posiada konfigurację i implementację najprostszych.

Zwykły użytkownik może również użyć tego oprogramowania do stworzyć lokalną platformę do robienia notatek dla siebie lub cokolwiek podobnego.

Zainstaluj MkDocs

Zainstaluj lokalnie

Zobaczmy, że instalacja MkDocs jest dość łatwa. Damy radę zainstaluj go za pomocą pip. Wystarczy otworzyć terminal (Ctrl + Alt + T) i napisać w nim:

pip install mkdocs

Po instalacji w katalogu roboczym uruchom następujące polecenie, aby zainicjuj witrynę:

mkdocs new mkdocspro

A potem do zacznij go podawać biegać:

cd mkdocspro

mkdocs serve

Wtedy możesz przejdź do localhost: 8000 (lub twój adres IP / nazwa hosta z portem 8000), aby zobaczyć, jak działa MkDocs.

Zainstaluj na serwerze nginx

Ponieważ jest to statyczny generator witryn, nie jest potrzebny silnik zaplecza, taki jak PHP lub Python. Będziesz mógł zaimplementować projekt MkDocs na swoim serwerze WWW (nginx, apache2) w ciągu minuty. Na przykład tutaj jest plik Konfiguracja wirtualnego hosta nginx:

server {
        server_name ejemplo.com;

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

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

Zastępuje example.com z domeną, którą masz na swoim serwerze. Będziesz też musiał się zmienić / var / www / mkdocspro / site ścieżką do podfolderu witryny na serwerze. Wtedy mamy tylko zrestartuj nginx poleceniem:

sudo service nginx restart

Teraz możesz przejść do example.com i zobaczyć, jak działa.

Zainstaluj inny motyw w Mkdocs

Domyślny motyw Mkdocs nie jest szczególnie dobry. Ale możesz zainstalować inny za minutę. Poniżej przedstawiono przykład instalacji innego motywu. Z którym mamy zamiar zainstaluj motyw materiału:

pip install mkdocs-material

Po instalacji, aby aktywować motyw, będziesz musiał wyedytuj swój plik mkdocs.yml i uczyń go podobnym do tego. Można dodać kilka opcji:

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'

Opcje są dość jasne. Ale oto kilka wyjaśnień:

• repo_url: jest URL repozytorium Git. Jeśli planujesz zintegrować Git bezpośrednio z projektem MkDocs, możesz użyć tej opcji, aby umożliwić użytkownikom edycję stron lub rozwidlenie projektu.
• edytuj_uri: To jest postfix do edycji stron w serwisie GitHub. Możesz to zmienić, jeśli używasz GitLab lub GitBucket.
• google_analytics: Nie ma panelu sterowania dla MkDocs. Dlatego wiedzieć kto odwiedza Twoją witrynę, musisz korzystać z Google Analytics. Ta opcja umożliwia wstawienie numeru śledzenia w celu powiązania konta z witryną.
• Disqus: Jeśli chcesz włączyć system komentowania Disqus na stronie internetowej możesz wstawić tutaj swoją krótką nazwę.
• motyw: The nazwa motywu, którego chcesz użyć. Będziesz musiał go zainstalować wcześniej, tak jak właśnie zrobiliśmy z motywem materiałowym. Będzie to nazwa, której użyjemy w przykładzie.

Zobacz zmiany w nowym motywie

Po zapisaniu pliku uruchom kompilację mkdocs w folderze mkdocsproject. Twoja witryna przyjmie domyślny wygląd i styl motywu Material:

Ważne: upewnij się, że zawsze uruchamiasz kompilację mkdocs po każdej modyfikacji że robisz w plikach. W przeciwnym razie nie zobaczysz żadnej zmiany.

istnieje wiele inne motywy i opcje aby skonfigurować to oprogramowanie. Możesz się z nimi skonsultować w oficjalna dokumentacja przez MkDocs. Oto lista możliwe opcje których możemy użyć.