Kitchen Sink

<docs-decorative-header title="Kitchen sink" imgSrc="adev/src/assets/images/components.svg"> <!-- markdownlint-disable-line --> This is a visual list of all custom components and styles for Angular.dev. </docs-decorative-header>

As a design system, this page contains visual and Markdown authoring guidance for:

• Custom Angular docs elements: docs-card, docs-callout, docs-pill, and docs-steps
• Custom text elements: alerts
• Code examples: docs-code
• Built-in Markdown styled elements: links, lists, headers, horizontal lines
• and more!

Get ready to:

1. Write...
2. great...
3. docs!

Headers (h2)

Smaller headers (h3)

Even smaller (h4)

Even more smaller (h5)

The smallest! (h6)

Cards

<docs-card> Attributes

Callouts

<docs-callout> Attributes

Pills

Pill rows are helpful as a sort of navigation with links to helpful resources.

<docs-pill> Attributes

Pills may also be used inline by themselves, but we haven't built that out yet.

Alerts

Alerts are just special paragraphs. They are helpful to call out (not to be confused with call-out) something that's a bit more urgent. They gain font size from context and are available in many levels. Try not to use alerts to render too much content, but rather to enhance and call attention to surrounding content.

Style alerts starting on a new line in Markdown using the format SEVERITY_LEVEL + : + ALERT_TEXT.

NOTE: Use Note for ancillary/additional information that's not essential to the main text.

TIP: Use Tip to call out a specific task/action users can perform, or a fact that plays directly into a task/action.

TODO: Use TODO for incomplete documentation that you plan to expand soon. You can also assign the TODO, e.g. TODO(emmatwersky): Text.

QUESTION: Use Question to pose a question to the reader, kind of like a mini-quiz that they should be able to answer.

SUMMARY: Use Summary to provide a two- or three-sentence synopsis of the page or section content, so readers can figure out whether this is the right place for them.

TLDR: Use TL;DR (or TLDR) if you can provide the essential information about a page or section in a sentence or two. For example, TLDR: Rhubarb is a cat.

CRITICAL: Use Critical to call out potential bad stuff or alert the reader they ought to be careful before doing something. For example, Warning: Running rm with the -f option will delete write-protected files or directories without prompting you.

IMPORTANT: Use Important for information that's crucial to comprehending the text or to completing some task.

HELPFUL: Use Best practice to call out practices that are known to be successful or better than alternatives.

NOTE: Heads up developers! Alerts can have a link and other nested styles (but try to use this sparingly)!.

Code

You can display code using the built in triple backtick:

example code

Or using the <docs-code> element.

@Component({ selector: 'example-code', template: '<h1>Hello World!</h1>', }) export class ComponentOverviewComponent {} </docs-code>

Styling the example

Here's a code example fully styled:

<docs-code path="adev/src/content/examples/hello-world/src/app/app.component-old.ts" header="A styled code example" language='ts' linenums highlight="[[3,7], 9]" preview visibleLines="[3,10]"> </docs-code>

We also have styling for the terminal, just set the language as shell:

npm install @angular/material --save

You can style standard Markdown triple backticks with attributes for enhanced presentation:

console.log('Hello, World!');
console.log('Awesome Angular Docs!');

<docs-code> Attributes

Multifile examples

You can create multifile examples by wrapping the examples inside a <docs-code-multifile>.

<docs-code-multifile path="adev/src/content/examples/hello-world/src/app/app.component.ts" preview> <docs-code path="adev/src/content/examples/hello-world/src/app/app.component.html" highlight="[1]" linenums/> <docs-code path="adev/src/content/examples/hello-world/src/app/app.component.css" /> </docs-code-multifile>

<docs-code-multifile> Attributes

Adding preview to your code example

Adding the preview flag builds a running example of the code below the code snippet. This also automatically adds a button to open the running example in Stackblitz.

NOTE: preview only works with standalone.

Styling example previews with Tailwind CSS

Tailwind utility classes can be used within code examples.

<docs-code-multifile path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.ts" preview> <docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.html" /> <docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.ts" /> </docs-code-multifile>

Tabs

Workflow

Style numbered steps using <docs-step>. Numbering is created using CSS (handy!).

<docs-workflow> and <docs-step> Attributes

Steps must start on a new line, and can contain docs-codes and other nested elements and styles.

To install the Angular CLI, open a terminal window and run the following command:

npm install -g @angular/cli

To create a new workspace and initial starter app:

• Run the CLI command ng new and provide the name my-app, as shown here:

  shellCopy

  ng new my-app
  

• The ng new command prompts you for information about features to include in the initial app. Accept the defaults by pressing the Enter or Return key.

  The Angular CLI installs the necessary Angular npm packages and other dependencies. This can take a few minutes.

  The CLI creates a new workspace and a simple Welcome app, ready to run. </docs-step>

1. Navigate to the workspace folder, such as my-app.

2. Run the following command:

   shellCopy

   cd my-app
   ng serve --open
   

The ng serve command launches the server, watches your files, and rebuilds the app as you make changes to those files.

The --open (or just -o) option automatically opens your browser to http://localhost:4200/. If your installation and setup was successful, you should see a page similar to the following. </docs-step>

Images and video

You can add images using the semantic Markdown image:

Add #small and #medium to change the image size

Add attributes using curly braces syntax

 

Embedded videos are created with docs-video and just need a src and alt:

Charts & Graphs

Write diagrams and charts using Mermaid by setting the code language to mermaid, all theming is built-in.

    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

  sequenceDiagram
      Alice->>+John: Hello John, how are you?
      Alice->>+John: John, can you hear me?
      John-->>-Alice: Hi Alice, I can hear you!
      John-->>-Alice: I feel great!

  pie title Pets adopted by volunteers
      "Dogs" : 386
      "Cats" : 85
      "Rats" : 15

Horizontal Line Divider

This can be used to separate page sections, like we're about to do below. These styles will be added by default, nothing custom needed.

The end!

Prefer / Avoid

const foo = 'bar';

const bar = 'foo';

const baz = 42;

<docs-code path="adev/src/content/examples/hello-world/src/app/app.component-old.ts" header="A styled code example" language='ts' linenums highlight="[[3,7], 9]" prefer> </docs-code>