Skip to main content

Viết Tài liệu

Bố cục tập tin​

Nguồn tài liệu của bạn phải được viết dưới dạng tệp Markdown thông thường (xem Viết bằng Markdown bên dưới) và được đặt trong thư mục tài liệu . Theo mặc định, thư mục này sẽ được đặt tên docsvà sẽ tồn tại ở cấp cao nhất của dự án của bạn, cùng với mkdocs.ymltệp cấu hình.

Dự án đơn giản nhất bạn có thể tạo sẽ trông giống như thế này:

mkdocs.yml docs/ index.md

Theo thông lệ, trang chủ dự án của bạn phải được đặt tên index.md(xem Trang chỉ mục bên dưới để biết chi tiết). Bất kỳ phần mở rộng tệp nào sau đây có thể được sử dụng cho các tệp nguồn Markdown của bạn: markdown, mdown, mkdn, mkd, md. Tất cả các tệp Markdown có trong thư mục tài liệu của bạn sẽ được hiển thị trong trang web đã xây dựng bất kể bất kỳ cài đặt nào.

Ghi chú

Các tệp và thư mục có tên bắt đầu bằng dấu chấm (ví dụ: .foo.mdhoặc .bar/baz.md) sẽ bị MkDocs bỏ qua. Điều này có thể được ghi đè bằng exclude_docsconfig .

Bạn cũng có thể tạo tài liệu nhiều trang bằng cách tạo nhiều tệp Markdown:

mkdocs.yml docs/ index.md about.md license.md

Bố cục tệp bạn sử dụng sẽ xác định các URL được sử dụng cho các trang được tạo. Với bố cục trên, các trang sẽ được tạo cho các URL sau:

/ /about/ /license/

Bạn cũng có thể đưa các tệp Markdown của mình vào các thư mục lồng nhau nếu cách đó phù hợp hơn với bố cục tài liệu của bạn.

docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md

Các tệp nguồn bên trong các thư mục lồng nhau sẽ khiến các trang được tạo bằng các URL lồng nhau, như sau:

/ /user-guide/getting-started/ /user-guide/configuration-options/ /license/

Bất kỳ tệp nào không được xác định là tệp Markdown (theo phần mở rộng tệp của chúng) trong thư mục tài liệu đều được MkDocs sao chép vào trang web đã xây dựng mà không thay đổi. Xem cách liên kết đến hình ảnh và phương tiện bên dưới để biết chi tiết.

Trang mục lục​

Khi một thư mục được yêu cầu, theo mặc định, hầu hết các máy chủ web sẽ trả về một tệp chỉ mục (thường được đặt tên là index.html) có trong thư mục đó nếu có. Vì lý do đó, trang chủ trong tất cả các ví dụ trên đã được đặt tên là index.md, mà MkDocs sẽ hiển thị index.htmlkhi xây dựng trang web.

Nhiều trang lưu trữ kho lưu trữ cung cấp cách xử lý đặc biệt cho các tệp README bằng cách hiển thị nội dung của tệp README khi duyệt nội dung của một thư mục. Do đó, MkDocs sẽ cho phép bạn đặt tên các trang chỉ mục của mình là README.mdthay vì index.md. Theo cách đó, khi người dùng duyệt mã nguồn của bạn, máy chủ lưu trữ có thể hiển thị trang chỉ mục của thư mục đó vì đó là tệp README. Tuy nhiên, khi MkDocs hiển thị trang web của bạn, tệp sẽ được đổi tên thành index.htmlđể máy chủ sẽ phục vụ nó như một tệp chỉ mục phù hợp.

Nếu cả index.mdtệp và một README.mdtệp khác được tìm thấy trong cùng một thư mục, thì index.mdtệp đó sẽ được sử dụng và README.mdtệp đó sẽ bị bỏ qua.

Cấu hình Trang và Điều hướng​

Thiết lập cấu hình nav trong mkdocs.ymltệp của bạn xác định những trang nào được bao gồm trong menu điều hướng trang web toàn cầu cũng như cấu trúc của menu đó. Nếu không được cung cấp, điều hướng sẽ được tự động tạo bằng cách khám phá tất cả các tệp Markdown trong thư mục tài liệu . Cấu hình điều hướng được tạo tự động sẽ luôn được sắp xếp theo thứ tự chữ cái và số theo tên tệp (ngoại trừ các tệp chỉ mục sẽ luôn được liệt kê đầu tiên trong một tiểu mục). Bạn sẽ cần phải xác định thủ công cấu hình điều hướng của mình nếu bạn muốn menu điều hướng của mình được sắp xếp theo cách khác.

Cấu hình điều hướng tối thiểu có thể trông như thế này:

nav: - index.md - about.md

Tất cả các đường dẫn trong cấu hình điều hướng phải liên quan đến docs_dir tùy chọn cấu hình. Nếu tùy chọn đó được đặt thành giá trị mặc định, docs, các tệp nguồn cho cấu hình trên sẽ nằm tại docs/index.mdvà docs/about.md.

Ví dụ trên sẽ tạo ra hai mục điều hướng ở cấp cao nhất và tiêu đề của chúng được suy ra từ nội dung của tệp Markdown hoặc, nếu không có tiêu đề nào được định nghĩa trong tệp, thì từ tên tệp. Để ghi đè tiêu đề trong cài navđặt, hãy thêm tiêu đề ngay trước tên tệp.

nav: - Home: index.md - About: about.md

Lưu ý rằng nếu tiêu đề được xác định cho một trang trong phần điều hướng, tiêu đề đó sẽ được sử dụng trên toàn bộ trang web cho trang đó và sẽ ghi đè lên bất kỳ tiêu đề nào được xác định trong chính trang đó.

Có thể tạo các tiểu mục điều hướng bằng cách liệt kê các trang liên quan với nhau dưới tiêu đề của một phần. Ví dụ:

nav: - Home: index.md - User Guide: - Writing your docs: writing-your-docs.md - Styling your docs: styling-your-docs.md - About: - License: license.md - Release Notes: release-notes.md

Với cấu hình trên, chúng ta có ba mục cấp cao nhất: "Trang chủ", "Hướng dẫn sử dụng" và "Giới thiệu". "Trang chủ" là liên kết đến trang chủ của trang web. Trong phần "Hướng dẫn sử dụng" có hai trang được liệt kê: "Viết tài liệu của bạn" và "Kiểu tài liệu của bạn". Trong phần "Giới thiệu" có hai trang nữa được liệt kê: "Giấy phép" và "Ghi chú phát hành".

Lưu ý rằng một section không thể có một trang được gán cho nó. Section chỉ là container cho các trang con và subsection. Bạn có thể lồng các section sâu tùy thích. Tuy nhiên, hãy cẩn thận để không làm cho người dùng của bạn quá khó khăn khi điều hướng qua trang web bằng cách làm phức tạp quá trình lồng nhau. Mặc dù các section có thể phản ánh cấu trúc thư mục của bạn, nhưng chúng không nhất thiết phải như vậy.

Bất kỳ trang nào không được liệt kê trong cấu hình điều hướng của bạn vẫn sẽ được hiển thị và bao gồm trong trang web đã xây dựng, tuy nhiên, chúng sẽ không được liên kết từ điều hướng toàn cầu và sẽ không được bao gồm trong các liên kết previousvà next. Các trang như vậy sẽ bị "ẩn" trừ khi được liên kết trực tiếp.

Viết bằng Markdown​

Các trang MkDocs phải được viết bằng Markdown , một ngôn ngữ đánh dấu nhẹ tạo ra các tài liệu văn bản thuần túy dễ đọc, dễ viết và có thể được chuyển đổi thành các tài liệu HTML hợp lệ theo cách có thể dự đoán được.

MkDocs sử dụng thư viện Python-Markdown để hiển thị tài liệu Markdown thành HTML. Python-Markdown gần như hoàn toàn tuân thủ với triển khai tham chiếu , mặc dù có một vài khác biệt rất nhỏ .

Ngoài cú pháp Markdown cơ bản phổ biến trong tất cả các triển khai Markdown, MkDocs còn hỗ trợ mở rộng cú pháp Markdown bằng tiện ích mở rộng Python-Markdown . Xem cài đặt cấu hình markdown_extensions của MkDocs để biết chi tiết về cách bật tiện ích mở rộng.

Theo mặc định, MkDocs bao gồm một số tiện ích mở rộng được đánh dấu bên dưới.

Liên kết nội bộ​

MkDocs cho phép bạn liên kết tài liệu của mình bằng cách sử dụng các liên kết Markdown thông thường . Tuy nhiên, có một số lợi ích bổ sung khi định dạng các liên kết đó dành riêng cho MkDocs như được nêu dưới đây.

Liên kết đến các trang​

Khi liên kết giữa các trang trong tài liệu, bạn chỉ cần sử dụng cú pháp liên kết Markdown thông thường , bao gồm đường dẫn tương đối đến tài liệu Markdown mà bạn muốn liên kết tới.

Please see the [project license](license.md) for further details.

Khi bản dựng MkDocs chạy, các liên kết Markdown này sẽ tự động được chuyển đổi thành siêu liên kết HTML đến trang HTML thích hợp.

Cảnh báo

Sử dụng đường dẫn tuyệt đối với liên kết không được hỗ trợ chính thức. Đường dẫn tương đối được MkDocs điều chỉnh để đảm bảo chúng luôn tương đối với trang. Đường dẫn tuyệt đối không được sửa đổi chút nào. Điều này có nghĩa là các liên kết sử dụng đường dẫn tuyệt đối của bạn có thể hoạt động tốt trong môi trường cục bộ của bạn nhưng chúng có thể bị hỏng khi bạn triển khai chúng lên máy chủ sản xuất của mình.

Nếu tệp tài liệu đích nằm trong một thư mục khác, bạn cần đảm bảo đưa vào bất kỳ đường dẫn thư mục tương đối nào trong liên kết.

Please see the [project license](../about/license.md) for further details.

Phần mở rộng toc được MkDocs sử dụng để tạo ID cho mọi tiêu đề trong tài liệu Markdown của bạn. Bạn có thể sử dụng ID đó để liên kết đến một phần trong tài liệu đích bằng cách sử dụng liên kết neo. HTML được tạo sẽ chuyển đổi chính xác phần đường dẫn của liên kết và giữ nguyên phần neo.

Please see the [project license](about.md#license) for further details.

Lưu ý rằng ID được tạo từ văn bản của tiêu đề. Tất cả văn bản được chuyển thành chữ thường và bất kỳ ký tự nào không được phép, bao gồm cả khoảng trắng, được chuyển thành dấu gạch ngang. Sau đó, các dấu gạch ngang liên tiếp được giảm xuống còn một dấu gạch ngang duy nhất.

Tiện ích mở rộng toc cung cấp một số thiết lập cấu hình mà bạn có thể thiết lập trong mkdocs.ymltệp cấu hình để thay đổi hành vi mặc định:

  • permalink

    Tạo liên kết cố định ở cuối mỗi tiêu đề. Mặc định: False.

    When set to True the paragraph symbol (¶ or ¶) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol (#) instead, do:

    markdown_extensions: - toc: permalink: "#"

  • baselevel

    Base level for headers. Default: 1.

    This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 (<h2>), do:

    markdown_extensions: - toc: baselevel: 2

    Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header (<h2>) in the HTML output.

  • separator

    Word separator. Default: -.

    Character which replaces white-space in generated IDs. If you prefer underscores, then do:

    markdown_extensions: - toc: separator: "_"

Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option.

markdown_extensions: - toc: permalink: "#" baselevel: 2 separator: "_"

Linking to images and media​

As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media.

For example, if your project documentation needed to include a GitHub Pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows:

mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png

To include images in your documentation source files, simply use any of the regular Markdown image syntaxes:

Cupcake indexer is a snazzy new project for indexing small cakes. ![Screenshot](img/screenshot.png) *Above: Cupcake indexer in progress*

Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor.

Linking from raw HTML​

Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.

Meta-Data​

MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any.

In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported:

  • template

    The template to use with the current page.

    By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment.

  • title

    The "title" to use for the document.

    MkDocs will attempt to determine the title of a document in the following ways, in order:

    1. A title defined in the nav configuration setting for a document.

    2. A title defined in the title meta-data key of a document.

    3. A level 1 Markdown header on the first line of the document body.
      (Setext-style headers are supported only since MkDocs 1.5.)

    4. The filename of a document.

    Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list.

YAML Style Meta-Data​

YAML style meta-data consists of YAML key/value pairs wrapped in YAML style delimiters to mark the start and/or end of the meta-data. The first line of a document must be ---. The meta-data ends at the first line containing an end deliminator (either --- or ...). The content between the delimiters is parsed as YAML.

--- title: My Document summary: A brief description of my document. authors: - Waylan Limberg - Tom Christie date: 2018-07-10 some_url: https://example.com --- This is the first paragraph of the document.

YAML is able to detect data types. Therefore, in the above example, the values of title, summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document.

MultiMarkdown Style Meta-Data​

MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this:

Title: My Document Summary: A brief description of my document. Authors: Waylan Limberg Tom Christie Date: January 23, 2018 blank-value: some_url: https://example.com This is the first paragraph of the document.

The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank.

If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string.

The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank.

Note

MkDocs không hỗ trợ các dấu phân cách kiểu YAML ( ---hoặc ...) cho siêu dữ liệu kiểu MultiMarkdown. Trên thực tế, MkDocs dựa vào sự có mặt hoặc không có các dấu phân cách để xác định xem siêu dữ liệu kiểu YAML hay siêu dữ liệu kiểu MultiMarkdown đang được sử dụng. Nếu các dấu phân cách được phát hiện, nhưng nội dung giữa các dấu phân cách không phải là siêu dữ liệu YAML hợp lệ, MkDocs không cố gắng phân tích cú pháp nội dung dưới dạng siêu dữ liệu kiểu MultiMarkdown.

Bảng​

Tiện ích mở rộng bảng bổ sung cú pháp bảng cơ bản vào Markdown, phổ biến trên nhiều triển khai. Cú pháp khá đơn giản và thường chỉ hữu ích cho dữ liệu bảng đơn giản.

Một bảng đơn giản trông như thế này:

First Header | Second Header | Third Header ------------ | ------------- | ------------ Content Cell | Content Cell | Content Cell Content Cell | Content Cell | Content Cell

Nếu muốn, bạn có thể thêm ống dẫn và ống đuôi vào mỗi dòng của bảng:

| First Header | Second Header | Third Header | | ------------ | ------------- | ------------ | | Content Cell | Content Cell | Content Cell | | Content Cell | Content Cell | Content Cell |

Chỉ định căn chỉnh cho từng cột bằng cách thêm dấu hai chấm vào các dòng phân cách:

First Header | Second Header | Third Header :----------- |:-------------:| -----------: Left | Center | Right Left | Center | Right

Lưu ý rằng các ô bảng không thể chứa bất kỳ phần tử cấp khối nào và không thể chứa nhiều dòng văn bản. Tuy nhiên, chúng có thể bao gồm Markdown nội tuyến như được định nghĩa trong các quy tắc cú pháp của Markdown .

Ngoài ra, bảng phải được bao quanh bởi các dòng trống. Phải có một dòng trống trước và sau bảng.

Khối mã được rào chắn​

Phần mở rộng khối mã có rào chắn bổ sung một phương pháp thay thế để xác định khối mã mà không cần thụt lề.

Dòng đầu tiên phải chứa 3 hoặc nhiều hơn 3 `ký tự dấu ngoặc ngược ( ) và dòng cuối cùng phải chứa cùng số ký tự dấu ngoặc ngược ( `):

``` Fenced code blocks are like Standard Markdown’s regular code blocks, except that they’re not indented and instead rely on start and end fence lines to delimit the code block. ```

Với cách tiếp cận này, ngôn ngữ có thể được tùy chọn chỉ định trên dòng đầu tiên sau dấu ngoặc kép để thông báo cho bất kỳ công cụ tô sáng cú pháp nào về ngôn ngữ được sử dụng:

```python def fn(): pass ```

Lưu ý rằng các khối mã được rào không thể thụt lề. Do đó, chúng không thể được lồng vào bên trong các mục danh sách, khối trích dẫn, v.v.

5:11:02 AM