Object doc

Một object metadata cho mỗi request website. Dùng cùng tên thuộc tính trong JSON, tag HTML và layout.

Thuộc tính

Giá trị mặc định và thứ tự ưu tiên

SEO mặc định website → doc trong JSON → tag doc trong HTML. Nguồn phía sau ghi đè từng trường được khai báo, giữ nguyên các trường khác. social cũng được ghép theo từng thuộc tính.

Theme cũ có title và seo trong JSON vẫn hoạt động: các giá trị này là fallback của trang trước khi áp dụng doc. Theme mới chỉ cần học và sử dụng doc.

Nếu không khai báo metadata riêng, object lấy từ SEO website. Nếu không có cả cấu hình website lẫn metadata trang, title và description có thể rỗng. Chuỗi rỗng và false là giá trị rõ ràng; chúng không có nghĩa là bỏ qua phép gán.

Khai báo trong trang JSON

{
  "layout": "main",
  "doc": {
    "title": "Skai — Nền tảng vận hành kinh doanh",
    "description": "Website, cửa hàng và ứng dụng trong một workspace.",
    "index": true,
    "follow": true,
    "social": { "image": "/assets/share.jpg" }
  },
  "sections": {},
  "order": []
}

Thiết lập trong HTML

{% doc title="Trang sản phẩm" description="Khám phá các sản phẩm của Skai." %}
{% doc type="article" title=article.title social.image=article.images.0 %}
{% doc index=false follow=false %}

Một tag nhận nhiều thuộc tính, biểu thức, filter và lời gọi hàm. Khi kế thừa layout, có thể đặt doc trực tiếp ngoài block, trong block được render hoặc trong section được include. Không cần tạo block head chỉ để khai báo metadata.

Khai báo trực tiếp trong page

{% extends "layouts/main.html" %}
{% doc title="Trang sản phẩm" description="Khám phá các sản phẩm của Skai." %}

{% block content %}
  <h1>Sản phẩm</h1>
{% endblock %}

Doc trực tiếp ngoài block chạy sau layout và các block, từ template cha đến trang con, theo thứ tự khai báo trong từng file. Mỗi key giữ lần gán cuối cùng; những trường không khai báo vẫn giữ fallback SEO. Biểu thức được đọc khi tag thực thi. Các tag như set hoặc if đặt ngoài block không tự chạy; nếu cần điều kiện hay truy vấn, giữ phần đó trong block được render hoặc dùng biểu thức trực tiếp trong doc.

Đọc trong layout

<title>{{ doc.title }}</title>
<meta name="description" content="{{ doc.description }}">
<meta property="og:type" content="{{ doc.type }}">
<link rel="canonical" href="{{ doc.canonical_url }}">
<meta property="og:title" content="{{ doc.social.title }}">
<meta property="og:image" content="{{ doc.social.image }}">

Đa ngôn ngữ

{% doc title=t("text.ok") description=t("home.description") %}

"text.ok" là chuỗi key truyền vào helper t(). text.ok không có dấu nháy là giá trị thuộc tính ok của object text. Bản thân tag doc không tự dịch chuỗi key.

Khi nào giá trị được áp dụng?

Tag ghi vào object tạm riêng của request. Gán lại cùng trường sẽ thay giá trị cũ ngay trong object tạm; không giữ mảng lịch sử. Với trang JSON, engine áp dụng trước khi render layout. Với HTML kế thừa layout, engine cập nhật metadata trong head sau khi render xong.

doc.index_str — chỉ thị index dạng chuỗi

Chỉ đọc. Engine suy ra từ doc.index: true trả index, false trả noindex. Giá trị được tính lại sau khi áp dụng metadata và quy tắc preview/404, không lưu vào page JSON.

{% doc index=false %}
<meta name="robots" content="{{ doc.index_str }}">

Kết quả: <meta name="robots" content="noindex">. Đặt meta trong layout, còn tag doc trong page hoặc section. Không khai báo index_str trong thẻ doc hay object doc của JSON; dùng boolean index làm nguồn dữ liệu.

doc.follow_str — chỉ thị follow dạng chuỗi

Chỉ đọc. Engine suy ra từ doc.follow: true trả follow, false trả nofollow. Tính lại sau khi áp dụng metadata, không lưu trong JSON và không khai báo trực tiếp qua thẻ doc.

{% doc index=false follow=true %}
<meta name="robots" content="{{ doc.index_str }},{{ doc.follow_str }}">

Kết quả: <meta name="robots" content="noindex,follow">. Hai key chỉ biểu diễn index/noindex và follow/nofollow, không tổng hợp các chỉ thị robots khác. Vẫn dùng boolean index/follow trong thẻ doc hoặc object doc của page JSON.