Angular documentation style guidelink
\nThis style guide covers the standards for writing Angular documentation on angular.io.\nThese standards ensure consistency in writing style, Markdown conventions, and code snippets.
\nPrerequisiteslink
\nBefore contributing to the Angular documentation, it is helpful if you are familiar with the following:
\n- \n
git: for an introduction, see GitHub's Git Handbook \nGitHub: for an introduction, see GitHub's Hello World \n- Markdown: see GitHub's Mastering Markdown \n
- Angular coding style: see the Angular Style Guide \n
- Google writing style: The Google Developer Documentation Style Guide is a comprehensive resource that this Angular documentation style guide builds upon. \n
Kinds of Angular documentationlink
\nThe categories of Angular documentation include:
\n- \n
- Guides: much of what's in the documentation section of angular.io.\nGuides walk the reader step-by-step through tasks to demonstrate concepts and are often accompanied by a working example.\nThese include Getting Started, Tour of Heroes, and pages about Forms, Dependency Injection, and HttpClient.\nContributing members of the community and Angular team members maintain this documentation in Markdown. \n
- API documentation: reference documents for the Angular Application Programming Interface, or API.\nThese are more succinct than guides and serve as a reference for Angular features.\nThey are especially helpful for people already acquainted with Angular concepts.\nThe angular.io infrastructure generates these documents from source code and comments that contributors edit. \n
- CLI documentation: the angular.io infrastructure generates these documents from CLI source code. \n
Markdown and HTMLlink
\nWhile the Angular guides are Markdown files, there are some sections within the guides that use HTML.
\nTo enable HTML in an Angular guide, always follow every opening and closing HTML tag with a blank line.
\nNotice the required blank line after the opening <div> in the following example:
It is customary but not required to precede the closing HTML tag with a blank line as well.
\nTitlelink
\nEvery guide document must have a title, and it should appear at the top of the page.
\nBegin the title with the Markdown # character, which renders as an <h1> in the browser.
A document can have only one <h1>.
Title text should be in Sentence case, which means the first word is capitalized and all other words are lower case.\nTechnical terms that are always capitalized, like \"Angular\", are the exception.
\nAlways follow the title with at least one blank line.
\nThe corresponding text in the left nav is in Title Case, which means that you use capital letters to start the first words and all principal words.\nUse lower case letters for secondary words such as \"in\", \"of\", and \"the\".\nYou can also shorten the nav title to fit in the column.
\nSectionslink
\nA typical document has sections.
\nAll section headings are in Sentence case, which means the first word is capitalized and all other words are lower case.
\nAlways follow a section heading with at least one blank line.
\nMain section headinglink
\nThere are usually one or more main sections that may be further divided into secondary sections.
\nBegin a main section heading with the Markdown ## characters, which renders as an <h2> in the browser.
Follow main section headings with a blank line and then the content for that heading as in the following example:
\nSecondary section headinglink
\nA secondary section heading is related to a main heading and falls textually within the bounds of that main heading.
\nBegin a secondary heading with the Markdown ### characters, which renders as an <h3> in the browser.
Follow a secondary heading by a blank line and then the content for that heading as in the following example:
\nAdditional section headingslink
\nWhile you can use additional section headings, the Table-of-contents (TOC) generator only shows <h2> and <h3> headings in the TOC on the right of the page.
Table of contentslink
\nMost pages display a table of contents or TOC.\nThe TOC appears in the right panel when the viewport is wide.\nWhen narrow, the TOC appears in a collapsible region near the top of the page.
\nYou don't need to create your own TOC by hand because the TOC generator creates one automatically from the page's <h2> and <h3> headers.
To exclude a heading from the TOC, create the heading as an <h2> or <h3> element with a class called 'no-toc'.
You can turn off TOC generation for the entire page by writing the title with an <h1> tag and the no-toc class.
Navigationlink
\nTo generate the navigation links at the top, left, and bottom of the screen, use the JSON configuration file, content/navigation.json.
If you have an idea that would result in navigation changes, file an issue first so that the Angular team and community can discuss the change.
\nFor a new guide page, edit the SideNav node in navigation.json.\nThe SideNav node is an array of navigation nodes.\nEach node is either an item node for a single document or a header node with child nodes.
Find the header for your page.\nFor example, a guide page that describes an Angular feature is probably a child of the Fundamentals header.
A header node child can be an item node or another header node.\nIf your guide page belongs under a sub-header, find that sub-header in the JSON.
\nAdd an item node for your guide page as a child of the appropriate header node as in the following example:
\nA navigation node has the following properties:
\n- \n
- \n
\nurl: the URL of the guide page, which is an item node only. \n - \n
\ntitle: the text displayed in the side nav. \n - \n
\ntooltip: text that appears when the reader hovers over the navigation link. \n - \n
\nchildren: an array of child nodes, which is a header node only. \n - \n
\nhidden: defined and settrueif this is a guide page that should not be displayed in the navigation panel. \n
Do not create a node that is both a header and an item node by specifying the url property of a header node.
Code snippetslink
\nAngular.io has a custom framework that enables authors to include code snippets directly from working example apps that are automatically tested as part of documentation builds.
\nIn addition to working code snippets, example code can include terminal commands, a fragment of TypeScript or HTML, or an entire code file.
\nWhatever the source, the doc viewer renders them as code snippets, either individually with the code-example component or as a tabbed collection with the code-tabs component.
\n\nWhen to use code fontlink
\nYou can display a minimal, inline code snippet with the Markdown backtick syntax.\nUse a single backtick on either side of a term when referring to code or the\nname of a file in a sentence.\nThe following are some examples:
\n- \n
- In the
app.component.ts, add alogger()method. \n - The
nameproperty isSally. \n - Add the component class name to the
declarationsarray. \n
The Markdown is as follows:
\nAuto-linking in code snippetslink
\nIn certain cases, when you apply backticks around a term, it may auto-link to the API documentation.\nIf you do not intend the term to be a link, use the following syntax:
\nHard-coded snippetslink
\nIdeally, you should source code snippets from working sample code, though there are times when an inline snippet is necessary.
\nFor terminal input and output, place the content between <code-example> tags, set the CSS class to code-shell, and set the language attribute to sh as in this example:
Inline, hard-coded snippets like this one are not testable and, therefore, intrinsically unreliable.\nThis example belongs to the small set of pre-approved, inline snippets that includes user input in a command shell or the output of some process.
\nIn all other cases, code snippets should be generated automatically from tested code samples.
\nFor hypothetical examples such as illustrations of configuration options in a JSON file, use the <code-example> tag with the header attribute to identify the context.
Compilable example appslink
\nOne of the Angular documentation design goals is that guide page code snippets be examples of working code.
\nAuthors meet this goal by displaying code snippets directly from working sample apps, written specifically for these guide pages.
\nFind sample apps in sub-folders of the content/examples directory of the angular/angular repository.\nAn example folder name is often the same as the guide page it supports.
A guide page might not have its own sample code.\nIt might refer instead to a sample belonging to another page.
\nThe Angular CI process runs all end-to-end tests for every Angular PR.\nAngular re-tests the samples after every new version of a sample and every new version of Angular.
\nWhen possible, every snippet of code on a guide page should be derived from a code sample file. You tell the Angular documentation engine which code file—or fragment of a code file—to display by configuring <code-example> attributes.
Displaying an entire code filelink
\nThis Angular documentation style guide that you are currently reading has its own example application, located in the content/examples/docs-style-guide folder.
The following <code-example> displays the sample's app.module.ts:
The following markup produces that snippet:
\nThe path attribute identifies the snippet's source file at the example app folder's location within content/examples.\nIn this example, that path is docs-style-guide/src/app/app.module.ts.
The header tells the reader where to find the file.\nFollowing convention, set the header attribute to the file's location within the example app's root folder.
Unless otherwise noted, all code snippets in this page are from sample source code located in the content/examples/docs-style-guide directory.
The documentation tooling reports an error if the file identified in the path does not exist or is in the .git-ignore file.\nMost .js files are in .git-ignore.
To include an ignored code file in your project and display it in a guide, remove it from .git-ignore. Update the content/examples/.gitignore as follows:
Displaying part of a code filelink
\nTo include a snippet of code within a sample code file, rather than the entire file, use the <code-example> region attribute.\nThe following example focuses on the AppModule class and its @NgModule() metadata:
To render the above example, the HTML in the Markdown file is as follows:
\nThe path points to the file, just as in examples that render the entire file.\nThe region attribute specifies a portion of the source file delineated by an opening #docregion and a closing #enddocregion.
You can see the class #docregion in the source file below.\nNotice the commented lines #docregion and #enddocregion in content/examples/docs-style-guide/src/app/app.module.ts with the name class.
The opening and ending #docregion lines designate any lines of code between them as being included in the code snippet.\nThis is why the import statements outside of the class #docregion are not in the code snippet.
For more information on how to prepare example app files for use in guides, see\nSource code markup.
\nCode snippet optionslink
\nSpecify the <code-example> output with the following attributes:
- \n
- \n
\npath: the path to the file in thecontent/examplesfolder. \n - \n
\nheader: the header of the code listing.\nThis is the title of the code snippet and can include the path and extra information such as whether the snippet is an excerpt. \n - \n
\nregion: displays the source file fragment with that region name; regions are identified by#docregionmarkup in the source file.\nSee Displaying a code snippet. \n - \n
\nlinenums: value may betrue,false, or anumber.\nThe default isfalse, which means that the browser displays no line numbers.\nThenumberoption starts line numbering at the given value.\nFor example,linenums=4sets the starting line number to 4. \n - \n
\nclass: code snippets can be styled with the CSS classesno-box,code-shell, andavoid. \n - \n
\nhideCopy: hides the copy button. \n - \n
\nlanguage: the source code language such asjavascript,html,css,typescript,json, orsh.\nThis attribute only applies to hard-coded examples. \n
Displaying bad codelink
\nOccasionally, you want to display an example of less than ideal code or design, such as with avoid examples in the Angular Style Guide.\nBecause it is possible for readers to copy and paste examples of inferior code in their own applications, try to minimize use of such code.
\nIn cases where you need unacceptable examples, you can set the class to avoid or have the word avoid in the filename of the source file.\nBy putting the word avoid in the filename or path, the documentation generator automatically adds the avoid class to the <code-example>.\nEither of these options frames the code snippet in bright red to grab the reader's attention.
Here's the markup for an \"avoid\" example in the\nAngular Style Guide that uses the word avoid in the path name:
Having the word \"avoid\" in the file name causes the browser to render the code snippet with a red header and border:
\nAlternatively, the HTML could include the avoid class as in the following:
Explicitly applying the class avoid causes the same result of a red header and red border:
Code Tabslink
\nCode tabs display code much like code-examples with the added advantage of displaying multiple code samples within a tabbed interface.\nEach tab displays code using a code-pane.
code-tabs attributeslink
\n- \n
linenums: The value can betrue,false, or a number indicating the starting line number.\nThe default isfalse. \n
code-pane attributeslink
\n- \n
path: a file in thecontent/examplesfolder \nheader: what displays in the header of a tab \nlinenums: overrides thelinenumsproperty at thecode-tabslevel for this particular pane.\nThe value can betrue,false, or a number indicating the starting line number.\nThe default isfalse. \n
The following example displays multiple code tabs, each with its own header.\nIt demonstrates showing line numbers in <code-tabs> and <code-pane>.
The linenums attribute set to true on <code-tabs> explicitly enables numbering for all panes.\nHowever, the linenums attribute set to false in the second <code-pane> disables line numbering only for itself.
Preparing source code for code snippetslink
\nTo display <code-example> and <code-tabs> snippets, add code snippet markup to sample source code files.
The sample source code for this page, located in content/examples/docs-style-guide, contains examples of every code snippet markup described in this section.
Code snippet markup is always in the form of a comment.\nThe default #docregion markup for a TypeScript or JavaScript file is as follows:
The documentation generation process erases these comments before displaying them in the documentation viewer, StackBlitz, and sample code downloads.
\nBecause JSON does not allow comments, code snippet markup doesn't work in JSON files.\nSee the section on JSON files for more information.
\n#docregionlink
\nUse #docregion in source files to mark code for use in <code-example> or <code-tabs> components.
The #docregion comment begins a code snippet region.\nEvery line of code after that comment belongs in the region until the code fragment processor encounters the end of the file or a closing #enddocregion.
The following src/main.ts is a an example of a file with a single #docregion at the top of the file.
As a result, the entire file is in the <code-example>.
Naming a #docregionlink
\nTo display multiple snippets from different fragments within the same file, give each fragment its own #docregion name as follows, where your-region-name is a hyphenated lowercase string:
Reference this region by name in the region attribute of the <code-example> or <code-pane> as follows:
Because the #docregion with no name is the default region, you do not need to set the region attribute when referring to the default #docregion.
Nesting a #docregionlink
\nPlace a #docregion within another #docregion as in the following example with a nested inner-region:
Combining code fragmentslink
\nCombine several fragments from the same file into a single code snippet by defining multiple #docregion sections with the same region name.\nThe following example defines two nested #docregion sections.
The inner region, class-skeleton, appears twice—once to capture the code that opens the class definition and a second time to capture the code that closes the class definition.
The #docplaster marker tells the processor what text string to use—that is, the \"plaster\"—to join each of the fragments into a single snippet.\nPlace the \"plaster\" text on the same line.\nFor example, #docplaster --- would use --- as the \"plaster\" text.\nIn the case of the previous file, the \"plaster\" text is empty so there will be nothing in between each fragment.
Without #docplaster, the processor inserts the default plaster—an ellipsis comment—between the fragments.
Here are the two corresponding code snippets for side-by-side comparison.
\nThe above example also demonstrates that one #docregion or #enddocregion comment can specify two region names, which is a convenient way to start or stop multiple regions on the same code line.\nAlternatively, you could put these comments on separate lines as in the following example:
JSON fileslink
\nThe <code-example> component cannot display portions of a JSON file because JSON forbids comments.\nHowever, you can display an entire JSON file by referencing it in the <code-example> src attribute.
For large JSON files, you could copy the nodes-of-interest into Markdown backticks, but as it's easy to mistakenly create invalid JSON that way, consider creating a JSON partial file with the fragment you want to display.
\nYou can't test a partial file nor use it in the application, but at least your editor can confirm that it is syntactically correct.\nYou can also store the partial file next to the original, so it is more likely that the author will remember to keep the two in sync.
\nHere's an example that excerpts certain scripts from package.json into a partial file named package.1.json.
In some cases, it is preferable to use the name of the full file rather than the partial.\nIn this case, the full file is package.json and the partial file is package.1.json.\nSince the focus is generally on the full file rather than the partial, using the name of the file the reader edits, in this example package.json, clarifies which file to work in.
Partial file naminglink
\nThe step-by-step nature of the guides necessitate refactoring, which means there are code snippets that evolve through a guide.
\nUse partial files to demonstrate intermediate versions of the final source code with fragments of code that don't appear in the final app.\nThe sample naming convention adds a number before the file extension, as follows:
\nRemember to exclude these files from StackBlitz by listing them in the stackblitz.json as illustrated here:
Live exampleslink
\nAdding <live-example></live-example> to a page generates two default links:
The first is a link to the StackBlitz example, which the default stackblitz.json file defines.\nYou can find the stackblitz.json file in the content/examples/example-app directory, where example-app is the sample application folder you're using for the guide.
By default, the documentation generator uses the name of the guide as the name of the example.\nSo, if you're working on router.md, and use <live-example></live-example> in the document, the documentation generator looks for content/examples/router.\nClicking this link opens the code sample on StackBlitz in a new browser tab.
The second link downloads the sample app.
\nDefine live examples by one or more stackblitz.json files in the root of a code sample folder.\nEach sample folder usually has a single unnamed definition file, the default stackblitz.json.
Live Example for named StackBlitzlink
\nYou can create additional, named definition files in the form name.stackblitz.json.\nThe Testing guide (aio/content/guide/testing.md) references a named StackBlitz file as follows:
The stackblitz attribute value of specs refers to the examples/testing/specs.stackblitz.json file.\nIf you were to leave out the stackblitz attribute, the default would be examples/testing/stackblitz.json.
Custom label and tooltiplink
\nChange the appearance and behavior of the live example with attributes and classes.\nThe following example gives the live example anchor a custom label and tooltip by setting the title attribute:
The browser renders the following:
\nYou can achieve the same effect by putting the label between the <live-example> tags:
The browser renders the following:
\nLive example from another guidelink
\nTo link to an example in a folder where the name is not the same as the current guide page, set the name attribute to the name of that folder.
For example, to include the Router guide example in this style guide, set the name attribute to router, that is, the name of the folder where that example resides.
Live Example without downloadlink
\nTo omit the download link, add the noDownload attribute.
The browser renders the following:
\nLive Example with download-onlylink
\nTo omit the live StackBlitz link and only link to the download, add the downloadOnly attribute.
The browser renders the following:
\nEmbedded live examplelink
\nBy default, a live example link opens a StackBlitz example in a separate browser tab.\nYou can embed the StackBlitz example within the guide page by adding the embedded attribute.
For performance reasons, StackBlitz does not start right away.\nInstead, the <live-example> component renders an image.\nClicking the image starts the process of launching the embedded StackBlitz within an <iframe>.
The following is an embedded <live-example> for this guide:
The browser renders the following <iframe> and a <p> with a link to download the example:
Anchorslink
\nEvery section header is also an anchor point.\nAnother guide page could add a link to this \"Anchors\" section with the following:
\nThe browser renders the following:
\nSee the \"Anchors\" section for details.
\nNotice that the above example includes a title of \"Style Guide—Anchors\".\nUse titles on anchors to create tooltips and improve UX.
\nWhen navigating within a page, you can omit the page URL when specifying the link that scrolls up to the beginning of this section, as in the following:
\nSection header anchorslink
\nWhile the documentation generator automatically creates anchors for headers based on the header wording, titles can change, which can potentially break any links to that section.
\nTo mitigate link breakage, add a custom anchor explicitly, just above the heading or text to which it applies, using the special syntax as follows:
Then reference that anchor like this:
\nThe browser renders the following:
\nThis is a link to that custom anchor name.
\nWhen editing a file, don't remove any anchors.\nIf you change the document structure, you can move an existing anchor within that same doc without breaking a link.\nYou can also add more anchors with more appropriate text.
\nAs an alternative, you can use the HTML <a> tag.\nWhen using the <a> tag, set the id attribute—rather than the name attribute because the documentation generator does not convert the name to the proper link URL.\nFor example:
Alerts and calloutslink
\nAlerts and callouts present warnings, extra detail, or references to related topics.
\nAn alert or callout should not contain anything essential to understanding the main content.\nInstructions or tutorial steps should be in the main body of a guide rather than in a subsection.
\nAlertslink
\nAlerts draw attention to short, important points.\nFor multi-line content, see callouts.
\nSee the live examples section for more information.
\nNote that at least one blank line must follow both the opening and closing <div> tags.\nA blank line before the closing </div> is conventional but not required.
There are three different levels for styling the alerts according to the importance of the content.
\nUse the following the alert class along with the appropriate is-helpful, is-important, or is-critical CSS class, as follows:
The browser renders the following:
\nA helpful, informational alert.
\nAn important alert.
\nA critical alert.
\nCalloutslink
\nCallouts, like alerts, highlight important points.\nUse a callout when you need a header and multi-line content.
\nIf you have more than two paragraphs, consider creating a new page or making it part of the main content.
\nCallouts use the same styling levels as alerts.
\nUse the CSS class callout in conjunction with the appropriate is-helpful, is-important, or is-critical class.\nThe following example uses the is-helpful class:
The browser renders the three styles as follows:
\nA helpful note. Use a helpful callout for information requiring explanation.\nCallouts are typically multi-line notes.\nThey can also contain code snippets.
\nAn important note. Use an important callout for significant information requiring explanation.\nCallouts are typically multi-line notes.\nThey can also contain code snippets.
\nA critical note. Use a critical callout for compelling information requiring explanation.\nCallouts are typically multi-line notes.\nThey can also contain code snippets.
\nWhen using callouts, consider the following points:
\n- \n
- The callout header text style is uppercase. \n
- The header does not render in the table of contents. \n
- You can write the callout body in Markdown. \n
- A blank line separates the
<header>tag from the Markdown content. \n - Avoid using an
<h2>,<h3>,<h4>,<h5>, or<h6>, as the CSS for callouts styles the<header>element. \n
Use callouts sparingly to grab the user's attention.
\nTreeslink
\nUse trees to represent hierarchical data such as directory structure.
\nHere is the markup for this file tree.
\nTableslink
\nUse HTML tables to present tabular data.
\n| Header Type | \nMarkdown | \nUse | \n
|---|---|---|
<h1> | \n # | \nTitle of page | \n
<h2> | \n ## | \n \n\n Second level headers \n | \n
<h3> | \n ### | \n\n Third level headers \n | \n
The following is the markup for this table:
\nImageslink
\nStore images in the content/images/guide directory in a folder with the same name as the guide page.\nBecause Angular documentation generation copies these images to generated/images/guide/your-guide-directory, set the image src attribute to the runtime location of generated/images/guide/your-guide-directory.
For example, images for this \"Angular documentation style guide\" are in the content/images/guide/docs-style-guide folder, but the src attribute specifies the generated location.
The following is the src attribute for the \"flying hero\" image belonging to this guide:
<img> tag Specify images using the <img> tag.\nDo not use the Markdown image syntax, .
For accessibility, always set the alt attribute with a meaningful description of the image.
Nest the <img> tag within a <div class=\"lightbox\"> tag, which styles the image according to the documentation standard.
Note that the HTML <img> element does not have a closing tag.
The browser renders the following:
\n![\"flying](\"generated/images/guide/docs-style-guide/flying-hero.png\")
\n Image captions and figure captionslink
\nA caption appears underneath the image as a concise and comprehensive summary of the image.\nCaptions are optional unless you are using numbered figures, such as Figure 1, Figure 2, and so on.\nIf you are using numbered figures in a page, follow the guidelines in Figure captions in the Google Developer Documentation Style Guide.
\nImage dimensionslink
\nThe doc generator reads the image dimensions from an image file and adds width and height attributes to the <img> tag automatically.
To control the size of the image, supply your own width and height attributes.
Here's the \"flying hero\" markup with a 200px width:
\nThe browser renders the following:
\n
Wide imageslink
\nTo prevent images overflowing their viewports, use image widths under 700px.\nTo display a larger image, provide a link to the actual image that the user can click to see the full size image separately, as in this example of source-map-explorer output from the \"Ahead-of-time Compilation\" guide:
![\"toh-pt6-bundle\"](\"generated/images/guide/docs-style-guide/toh-pt6-bundle.png\")
\n The following is the HTML for creating a link to the image:
\nImage compressionlink
\nFor faster load times, always compress images.\nConsider using an image compression web site such as tinypng.
\nFloated imageslink
\nYou can float the image to the left or right of text by applying the class=\"left\" or class=\"right\" attributes respectively.\nFor example:
\nThe browser renders the following:
\n
This text wraps around to the right of the floating \"flying hero\" image.
\nHeadings and <code-example> components automatically clear a floated image.\nTo explicitly clear a floated image, add <br class=\"clear\"> where the text should break.
\n
Generally, you don't wrap a floated image in a <figure> element.
Floats within a subsectionlink
\nIf you have a floated image inside an alert, callout, or a subsection, apply the clear-fix class to the <div> to ensure that the image doesn't overflow its container.\nFor example:
The browser renders the following:
\n
A subsection with Markdown formatted text.
\nHelp with documentation stylelink
\nFor specific language and grammar usage, a word list, style, tone, and formatting recommendations, see the Google Developer Documentation Style Guide.
\nIf you have any questions that this style guide doesn't answer or you would like to discuss documentation styles visit the Angular repo and file a documentation issue.
\n\n \n