Mkdocs, създайте документация благодарение на този софтуер с отворен код

В следващата статия ще разгледаме Mkdocs. Ако разработвате софтуер и търсите платформа за създаване на документация за един от вашите проекти. Или ако работите във фирма, която трябва да създаде вътрешна документация за персонала. Дори ако сте напреднал потребител, който иска да запази някои бележки. MkDocs е инструмент, който трябва да опитате.

Този софтуер е статичен генератор на сайтове, насочен към създаване на платформи за документация. Това е доста просто, красиво за гледане и лесно за настройка и внедряване. Е написано на python y simplemente изисква да създадете файловете си във формат 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 на уебсайта, можете да вмъкнете краткото си име тук.
• тема: Най- име на темата, която искате да използвате. Ще трябва да го инсталирате по-рано, както току-що направихме с темата на материала. Това ще бъде името, което ще използваме в примера.

Вижте промените в новата тема

След като запазите файла, стартирайте mkdocs build вътре в папката mkdocsproject. Вашият уебсайт ще приеме облика по подразбиране на темата Материал:

Важно: уверете се, че винаги изпълнявате mkdocs build след всяка модификация което правите във файловете. В противен случай няма да видите промяна.

има много други теми и опции за конфигуриране на този софтуер. Можете да ги консултирате в официална документация от MkDocs. Ето списък на възможни опции които можем да използваме.