Get Inspired
Docs
Blog
Articles
Handbook
Where to publish your content Components Content types
Add a project Add a doc Add a blog post Schedule a post Add an API Add a collection page Add a collection page Add an image or video Add an author Add a tag Add an iframe Add a Glitch embed Add a YouTube embed Add a landing page Display a banner Create anchor redirects Style guide
Extensions docs Web platform docs
Handbook
Where to publish your content Components Content types
Add a project Add a doc Add a blog post Schedule a post Add an API Add a collection page Add a collection page Add an image or video Add an author Add a tag Add an iframe Add a Glitch embed Add a YouTube embed Add a landing page Display a banner Create anchor redirects Style guide
Extensions docs Web platform docs

Extensions docs

Published on • Updated on

Metadata

Extensions documents should follow the conventions outlined in the Add a Doc and Add a Blog Post guides. One notable exception is that we do not use the tags and author YAML front matter properties in extensions docs.

Line wrapping

Extensions docs are wrapped at 100 characters. New content and updates to existing content must follow this convention save for the following exceptions:

  • The existing page is already wrapped at another offset.
    • You may continue wrapping the document at the current offset.
  • Rewrapping would introduce significant noise to a code review.
    • Limiting line wrapping normalization to the text blocks your PR touches.

Header IDs

Header IDs are automatically generated based on the content of the header. This means that renaming a header will also change the header's ID and break existing links to that header.

To make your documentation more resilient to change, authors should manually declare header IDs.

Do

### Common use cases {: #use-cases }

Don't

### Common use cases

Automatically generated IDs are brittle. If this header were renamed in a future revision, it would be given a new ID and all existing links to this section would break.

Header IDs should be short and meaningful. Use descriptive names that unambiguously identify the content of the section rather than a kebab cased version of the header's text value.

By convention, extensions docs strongly prefer named footer links over inline links. Named links have a couple of advantages over inline links.

  • Named links are typically shorter. This makes it much easier to read and work with the source markdown file.
  • Named links are easier to maintain. Authors can edit one link definition and update all uses of that link links across a given document.

Do

Lorem ipsum dolor [sit amet][mdn-global], consectetur adipiscing elit.
Quisque aliquam rutrum pellentesque. Ut tincidunt purus ex, eget 
congue lacus aliquet quis.

[mdn-global]: https://developer.mozilla.org/en-US/docs/Glossary/Global_object

Don't

Lorem ipsum dolor [sit
amet](https://developer.mozilla.org/en-US/docs/Glossary/Global_object),
consectetur adipiscing elit. Quisque aliquam rutrum pellentesque. Ut
tincidunt purus ex, eget congue lacus aliquet quis.

Inline links make the source markdown appear longer than the rendered output, increases the likelihood that a link will wrap across lines, and may make a single line extend past the wrap column.

When linking to other resources on developer.chrome.com, use the relative path from the site's root rather than a relative path from the page or a full URL.

Do

[doc-page]: /docs/extensions/page/

Don't

[doc-page]: https://develper.chrome.com/docs/extensions/page/

Absolute URLs force links to reference the live site rather than the development or preview servers we test against when authoring or reviewing changes.

Don't

[doc-page]: page/

Page-relative paths are harder to find and update than their root-relative counterparts. This makes them making them more likely to break when reorganizing site content.

Internal links should include a terminal slash.

Do

[doc-page]: /docs/extensions/dir/page/
[doc-page]: /docs/extensions/sub/dir/page/#header

Don't

[doc-page]: /docs/extensions/dir/page
[doc-page]: /docs/extensions/sub/dir/page#header

These links only work as expected if the Node.js redirect server is running, which may not be true in all cases. Including the terminal slash makes links more robust.

Code formatting

Code samples in extensions documentation should be formatted using the Chromium project's git cl format command. To use this command, you must first install depot_tools. See Using clang-format for additional details.

# Use this command to format JS files and code samples
git cl format --js <filename>

Placeholder convention

Placeholders should be styled with <code><var>PLACEHOLDER_NAME</var></code> in body copy and PLACEHOLDER_NAME in code blocks and inline code. New content and updates to existing content must follow this convention.

Do

chrome.runtime.sendMessage('EXTENSION_ID', MESSAGE, function() {
  if (chrome.runtime.lastError) {
    // Extension is not installed.
  }
}

Replace the following:

  • EXTENSION_ID: the ID of your extension.
  • MESSAGE: The message string or object to send to the extension.

Don't

chrome.runtime.sendMessage('<extension id>', <message>, function() {
  if (chrome.runtime.lastError) {
    // Extension is not installed.
  }
}

Updated on • Improve article

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.