Mkdocs, tạo tài liệu nhờ phần mềm mã nguồn mở này

Trong phần tiếp theo, chúng ta sẽ xem xét về Mkdocs. Nếu bạn phát triển phần mềm và tìm kiếm một nền tảng để tạo tài liệu cho một trong những dự án của bạn. Hoặc nếu bạn làm việc trong một công ty cần tạo tài liệu nội bộ cho nhân viên. Ngay cả khi bạn là người dùng nâng cao muốn lưu một số ghi chú. MkDocs là một công cụ mà bạn nên thử.

Phần mềm này là một trình tạo trang web tĩnh nhằm mục đích tạo ra các nền tảng tài liệu. Nó khá đơn giản, dễ nhìn và dễ thiết lập và triển khai. Là viết bằng trăn và đơn giản yêu cầu bạn tạo tệp của mình ở định dạng Markdown. Sau đó, sử dụng một tệp cấu hình YAML duy nhất, bạn có thể tạo một trang web tĩnh phù hợp với bạn.

Tiếp theo, chúng ta sẽ thấy việc lấy một trang web tài liệu hoàn chỉnh bằng MkDocs dễ dàng như thế nào. Còn nhiều người khác máy tạo trang web tĩnh tương tự, nhưng cái này có cấu hình và cách triển khai đơn giản nhất.

Một người dùng bình thường cũng có thể sử dụng phần mềm này để tạo một nền tảng cục bộ để ghi chú cho chính anh ta hoặc bất cứ điều gì khác tương tự.

Cài đặt MkDocs

Cài đặt cục bộ

Hãy thấy rằng việc cài đặt MkDocs khá dễ dàng. Chúng tôi sẽ có thể cài đặt nó bằng pip. Bạn chỉ cần mở một thiết bị đầu cuối (Ctrl + Alt + T) và viết vào đó:

pip install mkdocs

Sau khi cài đặt, trong thư mục làm việc của bạn, hãy chạy lệnh sau để khởi tạo một trang web:

mkdocs new mkdocspro

Và sau đó đến bắt đầu phục vụ nó chạy:

cd mkdocspro

mkdocs serve

Sau đó bạn có thể vào localhost: 8000 (hoặc địa chỉ IP / tên máy chủ của bạn với cổng 8000) để xem cách MkDocs hoạt động.

Cài đặt trên máy chủ nginx của bạn

Vì đây là một trình tạo trang web tĩnh, không cần công cụ phụ trợ như PHP hoặc Python. Bạn sẽ có thể triển khai dự án MkDocs trên máy chủ web của mình (nginx, apache2) sau một phút. Ví dụ, đây là cấu hình máy chủ ảo nginx:

server {
        server_name ejemplo.com;

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

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

Thay thế example.com với miền bạn có trên máy chủ của mình. Bạn cũng sẽ phải thay đổi / var / www / mkdocspro / site theo đường dẫn của thư mục con của trang web trên máy chủ của bạn. Sau đó, chúng tôi chỉ có khởi động lại nginx bằng lệnh sau:

sudo service nginx restart

Bây giờ bạn có thể truy cập example.com và thấy nó hoạt động.

Cài đặt một chủ đề khác trong Mkdocs

Chủ đề Mkdocs mặc định không đặc biệt tốt. Nhưng bạn có thể cài đặt một cái khác sau một phút. Sau đây là một ví dụ về cài đặt chủ đề khác. Với cái mà chúng ta sẽ cài đặt chủ đề vật liệu:

pip install mkdocs-material

Sau khi cài đặt, để kích hoạt chủ đề, bạn sẽ phải chỉnh sửa tệp mkdocs.yml của bạn và làm cho nó tương tự như thế này. Một số tùy chọn có thể được thêm vào:

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'

Các tùy chọn khá rõ ràng. Nhưng đây là một số giải thích:

• repo_url: là URL kho lưu trữ Git. Nếu bạn định tích hợp Git trực tiếp vào dự án MkDocs của mình, bạn có thể sử dụng tùy chọn này để cho phép mọi người chỉnh sửa các trang hoặc phân nhánh dự án.
• chỉnh sửa_uri: Đây là postfix để chỉnh sửa trang trên GitHub. Bạn có thể thay đổi nó nếu bạn đang sử dụng GitLab hoặc GitBucket.
• google_analytics: Không có bảng điều khiển cho MkDocs. Do đó, để biết ai truy cập trang web của bạn, bạn phải sử dụng Google Analytics. Tùy chọn này sẽ cho phép bạn chèn số theo dõi để liên kết tài khoản của bạn với trang web.
• Disqus: Nếu bạn muốn kích hoạt hệ thống nhận xét Disqus trên trang web, bạn có thể chèn tên viết tắt của mình tại đây.
• chủ đề: tên của chủ đề bạn muốn sử dụng. Bạn sẽ phải cài đặt nó trước đây, như chúng ta vừa làm với chủ đề material. Đây sẽ là tên mà chúng ta sẽ sử dụng trong ví dụ.

Xem các thay đổi của chủ đề mới

Sau khi lưu tệp, chạy bản dựng mkdocs bên trong thư mục mkdocsproject. Trang web của bạn sẽ áp dụng giao diện mặc định của chủ đề Material:

Quan trọng: đảm bảo luôn chạy bản dựng mkdocs sau mỗi lần sửa đổi mà bạn làm trong các tệp. Nếu không, bạn sẽ không thấy bất kỳ thay đổi nào.

Có rất nhiều các chủ đề và tùy chọn khác để cấu hình phần mềm này. Bạn có thể tham khảo ý kiến ​​của họ trong tài liệu chính thức bởi MkDocs. Đây là danh sách các lựa chọn khả thi mà chúng ta có thể sử dụng.