此页面由 Cloud Translation API 翻译。

页面元数据

DevSite 页面是网站上的单个内容单元。网页可以包含标题、正文、标头元素和元数据属性，这些属性控制着网站的各项功能。当用户访问某个网页的网址时，网站会根据内容页的属性呈现完整的网页，并在其中添加页眉、页脚和边栏等动态元素。默认行为针对技术文档页面进行了优化，但也可以针对其他用途（例如营销和着陆页）配置页面。

网页结构

DevSite 页面是由网站管理其一般外观和功能的网页。系统会显示 Google Developers 页面，其中包含几个公共区域。（并非所有网站都支持全部功能。）将鼠标悬停在图表上以获取标签。

site header

网站徽标、登录微件、搜索框和顶部导航栏。在整个网站上通用。

project bar

项目或产品名称，以及项目特有的微件（例如“反馈”链接）。此区域由项目元数据定义。

sidebar

图书级分层导航。此区域由图书元数据定义。

body

网页标题和网页内容。

page footer ("last updated")

网页专用的微件（例如“上次更新时间”通知）。可能还包含 CC 许可通知，它是项目元数据属性。

site footer

网站页脚链接、语言选择微件。在整个网站上通用。

HTML 源文件

<html devsite>
  <head>
    <title>Page title</title>
    <meta name="project_path" value="/path/to/_project.yaml" />
    <meta name="book_path" value="/path/to/_book.yaml" />
  </head>
  <body>

    <p>Body content goes here, implemented as HTML.</p>

  </body>
</html>

<html> 元素的 devsite 属性告知 DevSite 将其呈现为 DevSite 网页，而非一字不差的 HTML 素材资源。如果您的页面显示时没有格式，或者没有页眉或页脚，请检查 <html devsite> 是否显示在文件顶部附近。

<html>、<head> 和 <body> 元素是必需的，而且必须具有开始和结束标记。

典型页面还必须在 <head> 内包含一个 <title> 元素。请参阅网页标题。

特定的 <meta> 代码用于控制网页功能。本参考文档中介绍了这些方法。典型网页包含一个表示 _project.yaml 元数据文件的 "project_path" 元标记和一个表示 _book.yaml 元数据文件的 "book_path" 元标记。请参阅项目和图书。DevSite 识别的 <meta> 代码通常不会显示在最终页面中。

<head> 中的其他元素和 <body> 中的所有元素都会在最终页面中呈现。

Markdown 源文件


Project: /path/to/_project.yaml
Book: /path/to/_book.yaml

# Page title

Body content, specified in Markdown, goes here.

典型的网页必须包含标题（例如，# Page title）。请参阅网页标题。

特定元标记控制网页功能。本参考文档中介绍了这些方法。典型网页包含一个表示 _project.yaml 元数据文件的 Project: 元标记和一个表示 _book.yaml 元数据文件的 Book: 元标记。查看项目和图书。DevSite 识别的元标记通常不会显示在最终页面中。

项目和图书

项目由名为 _project.yaml 的项目元数据文件描述。图书由名为 _book.yaml 的图书元数据文件进行描述。这些文件会与网页和素材资源文件一起发布到网站上，并且可以翻译成多种语言。如需了解这些文件的结构和属性，请参阅项目元数据和图书元数据。

要将页面与项目相关联，请提供 project_path 属性。其值是 _project.yaml 文件的内容路径。

HTML

<meta name="project_path" value="/path/to/_project.yaml" />

Markdown

Project: /path/to/_project.yaml

如果页面没有 project_path 属性，则渲染时将不包含项目栏区域及其地图项。此页面不会被视为项目的一部分。

如需将页面与图书相关联，请提供 book_path 属性。其值是 _book.yaml 文件的内容路径。

HTML

<meta name="book_path" value="/path/to/_book.yaml" />

Markdown

Book: /path/to/_book.yaml

网页标题

<head>
  <title>Page title</title>
  ...
</head>

或者，在页面的 <body> 中将 <h1> 元素与 page-title 类一起使用。

HTML

<h1 class="page-title">Page title</h1>

Markdown

# Page title

项目首页不需要标题，

HTML

<meta name="no_page_title" value="true" />

Markdown

no_page_title: true

在特殊情况下，如果特殊布局不需要自动 <h1>，但页面仍需要窗口标题，您可以使用 "hide_page_heading" 属性保留标题，但隐藏标题：

HTML

<title>Page title</title>
<meta name="hide_page_heading" value="true" />

Markdown

hide_page_heading: true
# Page title

标题说明

许多 DevSite 网站的标头中都有说明。此字段在 _project.yaml 元数据文件中设置，并会自动显示在 DevSite 着陆页上。换言之，使用 _index.yaml 模板创建的网页会自动在 _project.yaml 文件中设置标头中呈现说明。

若要为页面替换此说明，您可以在 _index.yaml 文件的根目录中设置 description，或在 landing_page 对象的 header 对象中设置 hide_description: true，从而禁止此说明。

全宽版式

如果需要更好地控制布局，您可以指示 DevSite 放弃对网站页眉和项目栏下方以及网站页脚上方区域的布局的控制。为此，请将 "full_width" 元数据属性设置为 "true"。

HTML

<meta name="full_width" value="true" />

Markdown

full_width: true

上次更新日期

默认情况下，除 full-width 页面外，页面页脚区域会自动包含“上次更新时间”通知。在大多数情况下，这样可让用户一目了然地了解网页内容的时效性。

在少数情况下，这些信息可能会造成混淆，或者被产品团队视为机密。如需停用网页上的上次更新时间通知，请将 hide_last_updated 属性设置为 true：

HTML

<meta name="project_path" value="/time-travel/_project.yaml" />
<meta name="book_path" value="/time-travel/_book.yaml" />
<meta name="hide_last_updated" value="true" />

Markdown

Project: /time-travel/_project.yaml
Book: /time-travel/_book.yaml
hide_last_updated: true

您可以替换系统自动计算的“上次更新时间”将 refresh_date 元标记设置为 ISO 8601 格式的日期：

HTML

<meta name="project_path" value="/time-travel/_project.yaml" />
<meta name="book_path" value="/time-travel/_book.yaml" />
<meta name="refresh_date" value="2017-03-27" />

Markdown

Project: /time-travel/_project.yaml
Book: /time-travel/_book.yaml
refresh_date: 2017-03-27

页面描述

网页说明是对网页内容的文字摘要。如需为网页设置说明，请提供 <meta name="description" content="DESCRIPTION" /> 元素。请注意，说明文本位于名为 content 的属性中，而不是 value；此值与网络标准属性相符。

HTML

<meta name="description" content="It was the best of times, it was the blurst of times..." />

Markdown

description: It was the best of times, it was the blurst of times...

设置网页说明会使 <meta> 标记包含在最终页面中

映像路径

image_path 是指向社交媒体和 DevSite 功能（例如 recommendations 和 dynamic content）中表示此页面的图片的路径。设置完毕后，此图片将用作页面的 OpenGraph 图片，并替换项目的 social media 设置和 tenant site's 品牌设置。

HTML

<meta name="image_path" value="/site-assets/developers_64dp.png" />

Markdown

image_path: /site-assets/developers_64dp.png

关键字

keywords 字段是以英文逗号分隔的字符串列表，用于描述网页，可用于网站搜索和 Dynamic Content 等搜索和发现功能。

keywords 字段支持无维度关联的平面关键字（例如 gettingstarted），以及使用维度命名空间来表示文档与现实实体（例如编程语言、产品和事件）之间关系的结构化关键字（例如 product:ComputeEngine 或 language:Python3）。您可以向任何关键字字段添加这两种类型的 keywords。

如果您暂存的关键字不符合格式要求，则会在您使用的工具（通常是 DevSite 命令行工具或 DevSite Content Publisher）的输出中看到一条警告，其中包含该关键字格式正确的版本。

HTML

<meta name="keywords" value="spacetime,timetravel,product:Delorean" />

Markdown

keywords: spacetime, timetravel, product:Delorean