DocFX - Hướng dẫn sử dụng và tùy chỉnh Template

Giới thiệu

Template trong DocFX là công cụ mạnh mẽ giúp bạn tùy chỉnh giao diện và cách hiển thị tài liệu của mình. DocFX hỗ trợ nhiều template mặc định và cho phép người dùng tùy chỉnh template theo nhu cầu. Trong bài viết này, chúng ta sẽ tìm hiểu cách sử dụng, tùy chỉnh và áp dụng template trong DocFX.

1. Template trong DocFX là gì?

Template là một tập hợp các tệp HTML, CSS, JavaScript, và các tài nguyên khác, xác định cách trình bày nội dung tài liệu. DocFX cung cấp template mặc định và hỗ trợ xuất hoặc tạo template tùy chỉnh.

Các template phổ biến:

Default: Template mặc định, dễ sử dụng và phù hợp với hầu hết các dự án.
Custom: Template tùy chỉnh do người dùng tự tạo hoặc sửa đổi.

2. Template Metadata

Các mẫu bổ sung có sẵn tại .

Cách dễ nhất để tùy chỉnh giao diện của trang là sử dụng . Dưới đây là danh sách siêu dữ liệu được xác định trước:

Name

Type

Description

_appTitle

string

A string append to every page title.

_appName

string

The name of the site displayed after logo.

_appFooter

string

The footer HTML.

_appLogoPath

string

Path to the app logo.

_appLogoUrl

string

URL for the app logo.

_appFaviconPath

string

Favicon URL path.

_enableSearch

bool

Whether to show the search box.

_noindex

bool

Whether to include in search results

_disableContribution

bool

Whether to show the "Edit this page" button.

_gitContribute

object

Defines the repo and branch property of git links.

_gitUrlPattern

string

URL pattern of git links.

_disableNewTab

bool

Whether to render external link indicator icons and open external links in a new tab.

_disableNavbar

bool

Whether to show the navigation bar.

_disableBreadcrumb

bool

Whether to show the breadcrumb.

_disableToc

bool

Whether to show the TOC.

_disableAffix

bool

Whether to show the right rail.

_disableNextArticle

bool

Whether to show the previous and next article link.

_disableTocFilter

bool

Whether to show the table of content filter box.

_googleAnalyticsTagId

string

Enables Google Analytics web traffic analysis.

_lang

string

Primary language of the page. If unset, the <html> tag will not have lang property.

_layout

string

Determines the layout of the page. Supported values are landing and chromeless.

Name

Type

Description

_appTitle

string

A string append to every page title.

_appName

string

The name of the site displayed after logo.

_appFooter

string

The footer HTML.

_appLogoPath

string

Path to the app logo.

_appLogoUrl

string

URL for the app logo.

_appFaviconPath

string

Favicon URL path.

_enableSearch

bool

Whether to show the search box.

_enableNewTab

bool

Whether to open external links in a new tab.

_noindex

bool

Whether to include in search results

_disableContribution

bool

Whether to show the "Improve this Doc" and "View Source" buttons.

_gitContribute

object

Defines the repo and branch property of git links.

_gitUrlPattern

string

URL pattern of git links.

_disableNavbar

bool

Whether to show the navigation bar.

_disableBreadcrumb

bool

Whether to show the breadcrumb.

_disableToc

bool

Whether to show the TOC.

_disableAffix

bool

Whether to show the right rail.

_googleAnalyticsTagId

string

Enables Google Analytics web traffic analysis.

_lang

string

Primary language of the page. If unset, the <html> tag will not have lang property.

3. Cách sử dụng template

3.1. Áp dụng template mặc định

Trong file docfx.json, bạn có thể chỉ định template cần sử dụng bằng cách thêm cấu hình:

{
  "build": {
    "template": ["default"]
  }
}

3.2. Áp dụng nhiều template

DocFX hỗ trợ áp dụng nhiều template theo thứ tự ưu tiên:

{
  "build": {
    "template": ["custom-template", "default"]
  }
}

Nếu không tìm thấy tệp trong custom-template, DocFX sẽ tự động sử dụng tệp từ template default.

4. Tùy chỉnh template

DocFX cho phép bạn tùy chỉnh template để phù hợp với thương hiệu hoặc yêu cầu dự án.

4.1. Xuất template mặc định

Để tùy chỉnh, bạn cần xuất template mặc định và chỉnh sửa:

docfx template export default

Template sẽ được xuất vào thư mục templates/default.

4.2. Chỉnh sửa template

Trong thư mục template, bạn có thể chỉnh sửa:

HTML: Thay đổi cấu trúc giao diện.
CSS: Tùy chỉnh màu sắc, font chữ, và phong cách.
JavaScript: Thêm tính năng hoặc tương tác mới.

4.3. Áp dụng template tùy chỉnh

Sau khi chỉnh sửa, áp dụng template bằng cách cấu hình:

templates/
|-- default/
    |-- styles/        # Chứa file CSS
    |-- scripts/       # Chứa file JavaScript
    |-- partials/      # Các thành phần HTML tái sử dụng
    |-- layout.html    # Layout chính của trang
    |-- toc.html       # Giao diện Table of Contents
    |-- ...            # Các tệp khác

Mô tả các thành phần chính:

layout.html: Tệp HTML chính quyết định bố cục chung.
partials/: Chứa các phần giao diện có thể tái sử dụng, như header, footer.
styles/: Tùy chỉnh giao diện bằng CSS.
scripts/: Tích hợp các tính năng tương tác bằng JavaScript.

5. Tính năng nâng cao của template

5.1. Hỗ trợ Data Binding

DocFX hỗ trợ Liquid template, cho phép bạn sử dụng các biến và vòng lặp trong tệp HTML:

{{ page.title }}  <!-- Hiển thị tiêu đề trang -->
{% for item in model.items %}
    <a href="{{ item.href }}">{{ item.name }}</a>
{% endfor %}

5.2. Tích hợp Metadata

Bạn có thể sử dụng metadata để tùy chỉnh nội dung hiển thị:

{% if model.metadata.language == "en" %}
    <p>This is an English page</p>
{% else %}
    <p>This is a localized page</p>
{% endif %}

5.3. Chạy Post Processor

Bạn có thể thêm Post Processor để xử lý template sau khi build:

{
  "build": {
    "postProcessors": ["CustomPostProcessor"]
  }
}

Post Processor là script tùy chỉnh để sửa đổi output cuối cùng.

6. Mẹo tối ưu hóa khi tùy chỉnh template

Giữ nguyên backup template gốc: Trước khi chỉnh sửa, luôn sao lưu template mặc định để tránh lỗi không mong muốn.
Sử dụng CSS thay vì sửa HTML: Hạn chế chỉnh sửa HTML trực tiếp, sử dụng CSS để giữ tính nhất quán.
Kiểm tra tương thích: Sau khi chỉnh sửa, kiểm tra trên nhiều trình duyệt để đảm bảo giao diện hoạt động tốt.

7. Kết hợp template với đa ngôn ngữ

Nếu dự án hỗ trợ đa ngôn ngữ, bạn có thể tạo các file riêng cho mỗi ngôn ngữ trong template:

Tạo các file như layout.vi.html hoặc layout.en.html.
Sử dụng cấu hình ngôn ngữ trong docfx.json:

{
  "build": {
    "locales": ["en-us", "vi-vn"]
  }
}

8. Tài nguyên tham khảo

- [Tài liệu chính thức về template DocFX](https://dotnet.github.io/docfx/docs/template.html)
- [Hướng dẫn tùy chỉnh giao diện]()

Kết luận

Template trong DocFX là công cụ mạnh mẽ giúp bạn tạo ra tài liệu chuyên nghiệp và phù hợp với thương hiệu. Với bài viết này, bạn đã nắm được cách sử dụng và tùy chỉnh template để tạo ra các giao diện tài liệu độc đáo.

Nếu bạn có thắc mắc hoặc cần hỗ trợ thêm, hãy để lại bình luận bên dưới. Hãy thử ngay và chia sẻ kết quả của bạn nhé! 😊

PreviousDocFX - Hướng dẫn cấu hình file docfx.json NextETL Tools

Last updated 5 months ago

Was this helpful?

Giới thiệu

1. Template trong DocFX là gì?

Các template phổ biến:

Default: Template mặc định, dễ sử dụng và phù hợp với hầu hết các dự án.
Custom: Template tùy chỉnh do người dùng tự tạo hoặc sửa đổi.

2. Template Metadata

Các mẫu bổ sung có sẵn tại .

Cách dễ nhất để tùy chỉnh giao diện của trang là sử dụng . Dưới đây là danh sách siêu dữ liệu được xác định trước:

Name

Type

Description

_appTitle

string

A string append to every page title.

_appName

string

The name of the site displayed after logo.

_appFooter

string

The footer HTML.

_appLogoPath

string

Path to the app logo.

_appLogoUrl

string

URL for the app logo.

_appFaviconPath

string

Favicon URL path.

_enableSearch

bool

Whether to show the search box.

_noindex

bool

Whether to include in search results

_disableContribution

bool

Whether to show the "Edit this page" button.

_gitContribute

object

Defines the repo and branch property of git links.

_gitUrlPattern

string

URL pattern of git links.

_disableNewTab

bool

Whether to render external link indicator icons and open external links in a new tab.

_disableNavbar

bool

Whether to show the navigation bar.

_disableBreadcrumb

bool

Whether to show the breadcrumb.

_disableToc

bool

Whether to show the TOC.

_disableAffix

bool

Whether to show the right rail.

_disableNextArticle

bool

Whether to show the previous and next article link.

_disableTocFilter

bool

Whether to show the table of content filter box.

_googleAnalyticsTagId

string

Enables Google Analytics web traffic analysis.

_lang

string

Primary language of the page. If unset, the <html> tag will not have lang property.

_layout

string

Determines the layout of the page. Supported values are landing and chromeless.

Name

Type

Description

_appTitle

string

A string append to every page title.

_appName

string

The name of the site displayed after logo.

_appFooter

string

The footer HTML.

_appLogoPath

string

Path to the app logo.

_appLogoUrl

string

URL for the app logo.

_appFaviconPath

string

Favicon URL path.

_enableSearch

bool

Whether to show the search box.

_enableNewTab

bool

Whether to open external links in a new tab.

_noindex

bool

Whether to include in search results

_disableContribution

bool

Whether to show the "Improve this Doc" and "View Source" buttons.

_gitContribute

object

Defines the repo and branch property of git links.

_gitUrlPattern

string

URL pattern of git links.

_disableNavbar

bool

Whether to show the navigation bar.

_disableBreadcrumb

bool

Whether to show the breadcrumb.

_disableToc

bool

Whether to show the TOC.

_disableAffix

bool

Whether to show the right rail.

_googleAnalyticsTagId

string

Enables Google Analytics web traffic analysis.

_lang

string

Primary language of the page. If unset, the <html> tag will not have lang property.

3. Cách sử dụng template

3.1. Áp dụng template mặc định

Trong file docfx.json, bạn có thể chỉ định template cần sử dụng bằng cách thêm cấu hình:

{
  "build": {
    "template": ["default"]
  }
}

3.2. Áp dụng nhiều template

DocFX hỗ trợ áp dụng nhiều template theo thứ tự ưu tiên:

{
  "build": {
    "template": ["custom-template", "default"]
  }
}

Nếu không tìm thấy tệp trong custom-template, DocFX sẽ tự động sử dụng tệp từ template default.

4. Tùy chỉnh template

DocFX cho phép bạn tùy chỉnh template để phù hợp với thương hiệu hoặc yêu cầu dự án.

4.1. Xuất template mặc định

Để tùy chỉnh, bạn cần xuất template mặc định và chỉnh sửa:

docfx template export default

Template sẽ được xuất vào thư mục templates/default.

4.2. Chỉnh sửa template

Trong thư mục template, bạn có thể chỉnh sửa:

HTML: Thay đổi cấu trúc giao diện.
CSS: Tùy chỉnh màu sắc, font chữ, và phong cách.
JavaScript: Thêm tính năng hoặc tương tác mới.

4.3. Áp dụng template tùy chỉnh

Sau khi chỉnh sửa, áp dụng template bằng cách cấu hình:

templates/
|-- default/
    |-- styles/        # Chứa file CSS
    |-- scripts/       # Chứa file JavaScript
    |-- partials/      # Các thành phần HTML tái sử dụng
    |-- layout.html    # Layout chính của trang
    |-- toc.html       # Giao diện Table of Contents
    |-- ...            # Các tệp khác

Mô tả các thành phần chính:

layout.html: Tệp HTML chính quyết định bố cục chung.
partials/: Chứa các phần giao diện có thể tái sử dụng, như header, footer.
styles/: Tùy chỉnh giao diện bằng CSS.
scripts/: Tích hợp các tính năng tương tác bằng JavaScript.

5. Tính năng nâng cao của template

5.1. Hỗ trợ Data Binding

DocFX hỗ trợ Liquid template, cho phép bạn sử dụng các biến và vòng lặp trong tệp HTML:

{{ page.title }}  <!-- Hiển thị tiêu đề trang -->
{% for item in model.items %}
    <a href="{{ item.href }}">{{ item.name }}</a>
{% endfor %}

5.2. Tích hợp Metadata

Bạn có thể sử dụng metadata để tùy chỉnh nội dung hiển thị:

{% if model.metadata.language == "en" %}
    <p>This is an English page</p>
{% else %}
    <p>This is a localized page</p>
{% endif %}

5.3. Chạy Post Processor

Bạn có thể thêm Post Processor để xử lý template sau khi build:

{
  "build": {
    "postProcessors": ["CustomPostProcessor"]
  }
}

Post Processor là script tùy chỉnh để sửa đổi output cuối cùng.

6. Mẹo tối ưu hóa khi tùy chỉnh template

Giữ nguyên backup template gốc: Trước khi chỉnh sửa, luôn sao lưu template mặc định để tránh lỗi không mong muốn.
Sử dụng CSS thay vì sửa HTML: Hạn chế chỉnh sửa HTML trực tiếp, sử dụng CSS để giữ tính nhất quán.
Kiểm tra tương thích: Sau khi chỉnh sửa, kiểm tra trên nhiều trình duyệt để đảm bảo giao diện hoạt động tốt.

7. Kết hợp template với đa ngôn ngữ

Nếu dự án hỗ trợ đa ngôn ngữ, bạn có thể tạo các file riêng cho mỗi ngôn ngữ trong template:

Tạo các file như layout.vi.html hoặc layout.en.html.
Sử dụng cấu hình ngôn ngữ trong docfx.json:

{
  "build": {
    "locales": ["en-us", "vi-vn"]
  }
}

8. Tài nguyên tham khảo

- [Tài liệu chính thức về template DocFX](https://dotnet.github.io/docfx/docs/template.html)
- [Hướng dẫn tùy chỉnh giao diện]()

Kết luận

Nếu bạn có thắc mắc hoặc cần hỗ trợ thêm, hãy để lại bình luận bên dưới. Hãy thử ngay và chia sẻ kết quả của bạn nhé! 😊