Code blocks

Code blocks show source code with syntax highlighting. NgDoc adds file names, code groups, highlighted lines, and code loaded from real files, so examples can't drift from the code.

👀 See it

export const greet = (name: string): string => {

  return `Hello, ${name}!`;
};

This block loads its code from a real file, names it and highlights line 3.

🧰 Use it

Write a fenced code block with a language, then add attributes after the language:

```typescript name="greeting.ts" {3}
export const greet = (name: string): string => {
  const greeting = `Hello, ${name}!`;
  return greeting;
};
```

Attributes are separated by spaces. Values go in double quotes. Markdown and template syntax lists every attribute.

File names

```typescript name="my-file.ts"
const message = 'Hello world';
```

const message = 'Hello world';

Code groups

Blocks with the same group show as tabs. Each block's name is its tab label.

```bash group="install" name="npm"
npm install @ng-doc/core
```

```bash group="install" name="yarn"
yarn add @ng-doc/core
```

npm install @ng-doc/core

The first block is open by default. Add active to open another one:

```bash group="install-active" name="npm"
npm install @ng-doc/core
```

```bash group="install-active" name="yarn" active
yarn add @ng-doc/core
```

yarn add @ng-doc/core

Icons

icon shows an icon next to the name, in single blocks and in code groups.

```typescript name="app.ts" icon="angular"
@Component({ selector: 'app-root', template: '' })
export class App {}
```

@Component({ selector: 'app-root', template: '' })
export class App {}

💡 Tip

To add your own icons, see Icons.

Highlighted lines

Put line numbers in braces after the language. Separate them with commas, and use a dash for a range. With file, the numbers count the lines that the block shows: after the #L range or the snippet is applied and hidden lines are removed.

```typescript name="ng-doc.page.ts" {1,3-6}
import { NgDocPage } from '@ng-doc/core';

const MyPage: NgDocPage = {
  title: 'My page',
  mdFile: './index.md',
};

export default MyPage;
```

import { NgDocPage } from '@ng-doc/core';

const MyPage: NgDocPage = {
  title: 'My page',
  mdFile: './index.md',
};

export default MyPage;

Code from a file

file loads the code from a file, relative to the Markdown file. Leave the block empty. NgDoc shows the code as it is in the file, without reformatting it. The examples on this page load examples/greeting.ts:

export const greet = (name: string): string => {

  return `Hello, ${name}!`;
};

export const farewell = (name: string): string => {
  return `Goodbye, ${name}!`;
};

```typescript name="greeting.ts" file="./examples/greeting.ts"

```

Add #L and line numbers right after the closing quote to load only some lines. The numbers refer to lines in the file.

```typescript name="greeting.ts" file="./examples/greeting.ts"#L8-L10

```

export const farewell = (name: string): string => {
  return `Goodbye, ${name}!`;
};

Snippets from a file

Line numbers change whenever the file changes. To load a part of a file that stays put, mark it with the snippet comments that demos use (Snippets), and put # and the snippet's id right after the closing quote:

export class Greeter {
  // snippet#greeting
  greet(name: string): string {
    return `Hello, ${name}!`;
  }
  // snippet#greeting

  farewell(name: string): string {
    return `Goodbye, ${name}!`;
  }
}

```typescript name="greeter.ts" file="./greeter.ts"#greeting

```

The block shows the code between the two snippet#greeting comments:

greet(name: string): string {
  return `Hello, ${name}!`;
}

• The snippet comments aren't shown, and neither are the comments of snippets inside it. ng-doc-ignore-line works as in a whole file.
• The indentation that all its lines share is removed, so a snippet inside a class reads like top-level code. Otherwise NgDoc shows the code as it is in the file.
• #L with line numbers is a line range. Any other suffix is a snippet id: letters, digits and dashes, as in // snippet#greeting.
• An id that the file doesn't have, or a snippet without its closing comment, fails the build with CONTENT_SNIPPET_UNKNOWN, which names the id and the file.

Hiding lines

A comment with ng-doc-ignore-line hides lines from code that NgDoc loads from a file, from demos and from snippets. It removes the line with the comment and the line after it. Add a number to remove more lines after it: // ng-doc-ignore-line 3.

This is the source of examples/greeting.ts:

export const greet = (name: string): string => {
  // ng-doc-ignore-line
  console.debug('greet', name);

  return `Hello, ${name}!`;
};

Loaded with file, the comment and the console.debug line are gone:

export const greet = (name: string): string => {

  return `Hello, ${name}!`;
};

The comment works in //, /* */ and <!-- --> form, so you can use it in TypeScript, styles and templates.

🚧 Gotchas

Warning

Only the new engine loads snippets with file="…"#id. The legacy builders can't parse such a block and fail the build (Legacy builders).

Warning

The comment also removes the line after it. A comment at the end of a line of code, such as foo(); // ng-doc-ignore-line, removes that line and the next one.

Next: Images, video and embeds