Mkdocs, створюйте документацію завдяки цьому програмному забезпеченню з відкритим кодом

У наступній статті ми збираємось поглянути на Mkdocs. Якщо ви розробляєте програмне забезпечення і шукаєте платформа для створення документації для одного з ваших проектів. Або якщо ви працюєте у компанії, яка повинна створити внутрішню документацію для персоналу. Навіть якщо ви досвідчений користувач, який хоче зберегти деякі нотатки. MkDocs - це інструмент, який слід спробувати.

Це програмне забезпечення є статичним генератором веб-сайтів, спрямованим на створення платформ документації. Це досить просто, красиво на них подивитися, а також легко налаштувати та розгорнути. Є написаний на пітоні і просто вимагає створення файлів у форматі Markdown. Потім, використовуючи один файл конфігурації YAML, ви можете створити статичний веб-сайт, який вам підходить.

Далі ми побачимо, як легко отримати повний веб-сайт документації за допомогою MkDocs. Є багато інших генератори сайтів подібний статичний, але це має конфігурацію та реалізацію найпростіших.

Звичайний користувач також може використовувати це програмне забезпечення для створити локальну платформу для створення нотаток для себе чи чогось іншого подібного.

Встановіть MkDocs

Встановити локально

Побачимо, що встановити MkDocs досить просто. Ми зможемо встановіть його за допомогою pip. Вам просто потрібно відкрити термінал (Ctrl + Alt + T) і написати в ньому:

pip install mkdocs

Після встановлення у своєму робочому каталозі запустіть таку команду, щоб ініціалізувати сайт:

mkdocs new mkdocspro

А потім за почніть його подавати запустити:

cd mkdocspro

mkdocs serve

Тоді можна перейти до localhost: 8000 (або вашу IP-адресу / ім’я хосту з портом 8000), щоб побачити, як працює MkDocs.

Встановіть на своєму сервері nginx

Оскільки це статичний генератор сайтів, не потрібен серверний механізм, як PHP або Python. Ви зможете впровадити проект MkDocs на своєму веб-сервері (nginx, apache2) за хвилину. Наприклад, ось конфігурація віртуального хосту nginx:

server {
        server_name ejemplo.com;

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

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

Замінює example.com з доменом, який ви маєте на своєму сервері. Вам також доведеться переодягнутися / var / www / mkdocspro / site шляхом до підпапки сайту на вашому сервері. Тоді ми лише маємо перезапустіть nginx з наступною командою:

sudo service nginx restart

Тепер ви можете зайти на example.com і побачити, як це працює.

Встановіть іншу тему в Mkdocs

За замовчуванням тема Mkdocs не особливо хороша. Але ви можете встановити ще один за хвилину. Прикладом встановлення іншої теми буде наступний. З яким ми збираємось встановити тему матеріалу:

pip install mkdocs-material

Після встановлення, щоб активувати тему, вам доведеться відредагуйте файл mkdocs.yml і зробіть його подібним до цього. Можна додати кілька опцій:

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'

Варіанти цілком зрозумілі. Але ось кілька пояснень:

• repo_url: є URL-адреса сховища Git. Якщо ви плануєте інтегрувати Git безпосередньо у свій проект MkDocs, ви можете використовувати цю опцію, щоб дозволити людям редагувати сторінки або розгалужувати проект.
• edit_uri: Це постфікс для редагування сторінок на GitHub. Ви можете змінити його, якщо використовуєте GitLab або GitBucket.
• google_analytics: Для MkDocs немає панелі керування. Тому знати хто відвідує ваш веб-сайт, ви повинні використовувати Google Analytics. Цей параметр дозволить вам вставити номер відстеження, щоб пов’язати свій обліковий запис із веб-сайтом.
• Disqus: Якщо ви хочете увімкнути систему коментарів Disqus на веб-сайті ви можете вставити тут своє коротке ім'я.
• тема: The назва теми, яку ви хочете використовувати. Вам доведеться встановити його раніше, як ми щойно зробили з темою матеріалу. Це буде назва, яку ми використаємо у прикладі.

Дивіться зміни нової теми

Після збереження файлу запустити mkdocs build всередині папки mkdocsproject. Ваш веб-сайт буде мати типовий зовнішній вигляд теми "Матеріал":

Важливо: переконайтеся, що завжди запускаєте mkdocs build після кожної модифікації що ви робите у файлах. В іншому випадку ви не побачите жодних змін.

є багато інші теми та варіанти для налаштування цього програмного забезпечення. Ви можете проконсультуватися з ними в офіційна документація від MkDocs. Ось список можливі варіанти що ми можемо використовувати.