MkDocks
Nếu bạn kỳ vọng đây là tài liệu hướng dẫn chi tiết về cách sử dụng mkdocs nhưng thực tế bản chất tài liệu này dành cho người có chút hiểu biết về lập trình cũng như cấu hình phần mềm mkdocs. Các thông tin trong phần này được hình thành từ quá trình tôi mày mò xây dựng website này. Tôi thấy hữu ích và lưu lại để sau này có chỗ để tra cứu nhanh chóng.
Quá trình tiếp cận Mkdocs
Cài đặt và cấu hình cơ bản phần mềm
Cài đặt python, pip thông qua Conda
Để cài đặt Python thông qua Conda, bạn có thể thực hiện các bước sau:
- Tải xuống và cài đặt Miniconda hoặc Anaconda:
- Truy cập trang web của Miniconda hoặc Anaconda và tải xuống phiên bản phù hợp với hệ điều hành.
- Thực hiện các bước cài đặt theo hướng dẫn trên màn hình.
- Mở Command Prompt hoặc Terminal:
Sau khi cài đặt xong, mở Command Prompt (trên Windows) hoặc Terminal (trên macOS hoặc Linux).
- Tạo môi trường trong conda:
- Cài đặt pip vào môi trường myens:
- Để cài đặt một gói phần mềm trong python có thể sử dụng conda hoặc pip: Cài đặt với conda Cài đặt với pip
Cài đặt mkdocs, mkdocs material
MKDOCS
MkDocs là một công cụ mạnh mẽ và linh hoạt được sử dụng để tạo tài liệu tĩnh từ các tệp Markdown. Nó được thiết kế đặc biệt cho việc viết tài liệu dự án và cung cấp giao diện thân thiện với người dùng cùng với nhiều tính năng hấp dẫn.
Đặc điểm chính của MkDocs:
-
Dễ sử dụng: MkDocs sử dụng các tệp Markdown để viết nội dung, cho phép người dùng dễ dàng tạo và chỉnh sửa tài liệu mà không cần phải lo lắng về cú pháp phức tạp.
-
Giao diện thân thiện: Giao diện của MkDocs trực quan và dễ sử dụng, giúp người dùng dễ dàng điều hướng và tìm kiếm thông tin.
-
Chủ đề tùy chỉnh: MkDocs hỗ trợ nhiều chủ đề giao diện đẹp mắt và bạn cũng có thể tùy chỉnh giao diện theo nhu cầu riêng.
-
Tích hợp dễ dàng: MkDocs có thể dễ dàng tích hợp với các hệ thống kiểm soát phiên bản như Git, giúp quản lý và theo dõi các thay đổi trong tài liệu.
-
Xây dựng trang web tĩnh: MkDocs tạo ra các trang web tĩnh có thể được triển khai trên bất kỳ máy chủ web nào, bao gồm cả GitHub Pages, Netlify, và nhiều dịch vụ khác.
Cài đặt và sử dụng MkDocs:
Cài đặt MkDocs:
Tạo dự án
Chạy MkDocs trong chế độ phát triển: Xây dựng trang web tĩnh: Kết quả sẽ được lưu trong thư mục site.Material for MkDocs
Material for MkDocs là một giao diện đẹp mắt, nhanh chóng và linh hoạt cho việc tạo tài liệu dự án bằng Markdown. Đây là một phần mở rộng cho MkDocs, một công cụ tạo trang web tĩnh2. Dưới đây là một số tính năng nổi bật của Material for MkDocs:
-
Giao diện đẹp mắt và tùy chỉnh: Material for MkDocs cung cấp một giao diện hiện đại và thân thiện, dễ dàng tùy chỉnh về màu sắc, chữ, biểu tượng, logo và nhiều hơn nữa.
-
Hỗ trợ tìm kiếm: Tài liệu tạo bởi Material for MkDocs có thể được tìm kiếm một cách nhanh chóng và hiệu quả.
-
Hỗ trợ các thiết bị khác nhau: Giao diện tự động điều chỉnh để phù hợp với màn hình của các thiết bị khác nhau như máy tính để bàn, máy tính bảng và điện thoại di động.
-
Tích hợp mạng xã hội: Material for MkDocs hỗ trợ tích hợp các plugin mạng xã hội, giúp tăng cường sự tham gia khi chia sẻ liên kết đến tài liệu của bạn.
-
Dễ dàng mở rộng: Material for MkDocs có thể dễ dàng mở rộng và cung cấp nhiều tùy chọn để thay đổi ngoại hình và hành vi.
Cài đặt Material for MkDocs:
Cài đặt với pip:
Thêm vào tệp cấu hình mkdocs.yml:
Chạy MkDocs để xem tài liệu:
Cấu hình files mkdocs.yml
Đây là files mkdocs của dự án này
site_name: Dược liệu Việt nam
theme:
name: material
font:
text: Ubuntu
code: Ubuntu Mono
icon:
logo: fontawesome/solid/house
favicon: fontawesome/solid/star
admonition:
note: octicons/tag-16
abstract: octicons/checklist-16
info: octicons/info-16
tip: octicons/squirrel-16
success: octicons/check-16
question: octicons/question-16
warning: octicons/alert-16
failure: octicons/x-circle-16
danger: octicons/zap-16
bug: octicons/bug-16
example: octicons/beaker-16
quote: octicons/quote-16
palette:
# Palette toggle for light mode
- scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
primary: deep purple
accent: deep purple
# Palette toggle for dark mode
- scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.instant
- navigation.instant.progress
- navigation.instant.preview
- navigation.tracking
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
- navigation.sections
- navigation.expand
- navigation.top
- search.suggest
- search.highlight
- Search.share
- navigation.sections
- navigation.path
- navigation.footer
- toc.integrate
- toc.follow
nav:
- Home: index.md
- Dược liệu:
- Dược liệu/index.md
- Mạn Kinh Tử (Quả): Dược liệu/Mạn Kinh Tử (Quả)/Mạn Kinh Tử (Quả).md
- Măng Cụt (Vỏ Quả): Dược liệu/Măng Cụt (Vỏ Quả)/Măng Cụt (Vỏ Quả).md
- Viễn Chí (Rễ): Dược liệu/Viễn Chí (Rễ)/Viễn Chí (Rễ).md
- Khổ Hạnh Nhân: Dược liệu/Khổ Hạnh Nhân/Khổ Hạnh Nhân.md
- Vàng Đắng (Thân): Dược liệu/Vàng Đắng (Thân)/Vàng Đắng (Thân).md
- Ô Đầu (Rễ Củ): Dược liệu/Ô Đầu (Rễ Củ)/Ô Đầu (Rễ Củ).md
- Ô Đầu (Rễ Củ): Dược liệu/Ô Đầu (Rễ Củ)/Ô Đầu (Rễ Củ).md
- Nhàu (Rễ): Dược liệu/Nhàu (Rễ)/Nhàu (Rễ).md
- Cây Ổi (Lá): Dược liệu\Cây Ổi (Lá)\Cây Ổi (Lá).md
- Blog:
- blog/index.md
- About:
- About me: About/AboutMe.md
- About website: About/AboutProject.md
- Tags: tags.md
- Categories: categories.md
plugins:
- search
- tags:
tags_file: tags.md
- blog
- glightbox:
touchNavigation: true
loop: false
effect: zoom
slide_effect: slide
width: 100%
height: auto
zoomable: true
draggable: true
skip_classes:
- custom-skip-class-name
auto_caption: false
caption_position: bottom
background: white
shadow: true
manual: false
- social
- mkdocstrings
- markdown-exec
- awesome-pages
- categories:
generate_index: true
verbose: false
base_name: 'categories'
section_title: 'Categories'
no_nav: false
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- attr_list
- md_in_html
- def_list
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.critic
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
- pymdownx.blocks.caption
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
