Page metadata
A DevSite page is a single unit of content on a site. A page can have a title, a body, header elements, and metadata attributes that control the features of the site. When a user visits the URL for a page, the site renders a complete web page based on the content page's properties, adding dynamic elements such as the header, footer, and sidebar. Default behaviors are optimized for pages of technical documentation, but a page can also be configured for other uses, such as marketing and landing pages.
Structure of a page
A DevSite page is a web page whose general appearance and features are managed by the site. A page on Google Developers is displayed with several common areas. (Not all sites support all features.) Hover your mouse over the diagram for labels.
site header
The site logo, sign-in widget, search box, and top nav. Common across the entire site.
project bar
The project or product title, and project-specific widgets (such as the "Feedback" link). This area is defined by project metadata.
sidebar
Book-wide hierarchical navigation. This area is defined by book metadata.
body
The page title, and the content of the page.
page footer ("last updated")
Page-specific widgets (such as the "Last updated" notice). May also contain a CC license notice, which is a project metadata attribute.
site footer
The site footer links, the language select widget. Common across the entire site.
HTML source files
<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>
The devsite attribute of the <html> element tells DevSite that this should be rendered as a DevSite page and not verbatim as an HTML asset. If your page is appearing without formatting or a header or footer, check that <html devsite> appears near the top of your file.
The <html>, <head>, and <body> elements are required and must have opening and closing tags.
A typical page must also have a <title> element, inside the <head>. See Page title.
Specific <meta> tags control page features. These are described in this reference. A typical page has a "project_path" meta tag, which refers to a _project.yaml metadata file, and a "book_path" meta tag, which refers to a _book.yaml metadata file. See Projects and books. <meta> tags recognized by DevSite usually do not appear in the final page.
Other elements in the <head> and all elements in the <body> are rendered in the final page.
Markdown source files
Project: /path/to/_project.yaml
Book: /path/to/_book.yaml
# Page title
Body content, specified in Markdown, goes here.
A typical page must have a title (e.g., # Page title). See Page title.
Specific meta tags control page features. These are described in this reference. A typical page has a Project: meta tag, which refers to a _project.yaml metadata file, and a Book: meta tag, which refers to a _book.yaml metadata file. See Projects and books. Meta tags recognized by DevSite usually do not appear in the final page.
Projects and books
A project is described by a project metadata file named _project.yaml. A book is described by a book metadata file named _book.yaml. These files are published to the site along with page and asset files, and can be translated into multiple languages. See Project metadata and Book metadata for information about the structure and attributes of these files.
To associate a page with a project, provide the project_path attribute. Its value is the content path to the _project.yaml file.
HTML
<meta name="project_path" value="/path/to/_project.yaml" />
Markdown
Project: /path/to/_project.yaml
If a page does not have a project_path attribute, it will be rendered without the project bar region and its features. The page will not be considered part of a project.
To associate a page with a book, provide the book_path attribute. Its value is the content path to the _book.yaml file.
HTML
<meta name="book_path" value="/path/to/_book.yaml" />
Markdown
Book: /path/to/_book.yaml
Page title
<head>
<title>Page title</title>
...
</head>
Or use an <h1> element with the page-title class in the <body> of the page.
HTML
<h1 class="page-title">Page title</h1>
Markdown
# Page title
Project home pages do not need titles,
HTML
<meta name="no_page_title" value="true" />
Markdown
no_page_title: true
In special cases where the automatic <h1> is not desired for a special layout but a page still needs a window title, you can keep the title but hide the heading with the "hide_page_heading" attribute:
HTML
<title>Page title</title>
<meta name="hide_page_heading" value="true" />
Markdown
hide_page_heading: true
# Page title
Header description
Many DevSite sites have a description in the header. This is set in the _project.yaml metadata file and is automatically displayed on DevSite landing pages. In other words, pages that are created using _index.yaml templating will automatically render a description in the header, which is set in the _project.yaml file.
This description can be overridden for the page by setting a description at the root of the _index.yaml file, or suppressed by setting hide_description: true within the header object of the landing_page object.
Full width layout
If more control over layout is needed, you can tell DevSite to relinquish control over the layout for the area below the site header and project bar and above the site footer. To do so, set the "full_width" metadata attribute to "true".
HTML
<meta name="full_width" value="true" />
Markdown
full_width: true
Last updated date
By default, except on full-width pages, the page footer region includes an automatic "last updated" notice. In most cases, this gives users a straightforward signal about the freshness of the content on the page.
In a few cases, this information may be confusing or may be considered confidential by the product team. To disable the last-updated notice on a page, set the hide_last_updated attribute to 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
You can override the automatically calculated "last updated" date by setting the refresh_date meta tag to a date in ISO 8601 format:
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
Page description
The description of a page is a textual summary of the content of the page. To set a description for a page, provide a <meta name="description" content="DESCRIPTION" /> element. Notice that the description text goes in an attribute named content, not value; this matches the web standard attribute.
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...
Setting the page description causes the <meta> tag to be included on the final page
Image path
The image_path is the path to the image that represents this page in social media and DevSite features like recommendations and dynamic content. When set, this image will be used as the page's OpenGraph image, overriding the project's social media settings and the tenant site's branding settings.
HTML
<meta name="image_path" value="/site-assets/developers_64dp.png" />
Markdown
image_path: /site-assets/developers_64dp.png
Keywords
The keywords field is a comma-delimited list of strings that describe the page and are used in search and discovery features like site search and Dynamic Content.
The keywords field supports flat keywords with no dimensional association (for example, gettingstarted) and structured keywords that use dimensional namespaces to represent the relationship between documents and real-world entities like programming languages, products, and events (for example, product:ComputeEngine or language:Python3). You can add both types of keywords to any keywords field.
If you stage a keyword that does not conform to formatting requirements, you will see a warning with the correctly formatted version of your keyword in the output of the tool you have used (usually the DevSite command-line tool or the DevSite Content Publisher).
HTML
<meta name="keywords" value="spacetime,timetravel,product:Delorean" />
Markdown
keywords: spacetime, timetravel, product:Delorean