<commit_before># Paragraph

> Everything (text, images, graphs etc) in OpenXML is organized in paragraphs.

!> Paragraphs requires an understanding of [Sections](usage/sections.md).

You can create `Paragraphs` in the following ways:

### Shorthand

```ts
import { Paragraph } from "docx";

const paragraph = new Paragraph("Short hand Hello World");
```

### Children Method

This method is useful for adding different [text](usage/text.md) with different styles, [symbols](usage/symbols.md), or adding [images](usage/images.md) inline.

```ts
const paragraph = new Paragraph({
    children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World"), new SymbolRun("F071")],
});
```

### Explicit

```ts
const paragraph = new Paragraph({
    text: "Short hand notation for adding text.",
});
```

After you create the paragraph, you must add the paragraph into a `section`:

```ts
const doc = new Document({
    sections: [{
        children: [paragraph],
    }];
});
```

Or the preferred convention, define the paragraph inside the section and remove the usage of variables:

```ts
const doc = new Document({
    sections: [{
        children: [
            new Paragraph({
                children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")],
            }),
        ],
    }];
});
```

## Options

This is the list of options for a paragraph. A detailed explanation is below:

| Property                       | Type                                                                                                                | Mandatory? | Possible Values                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| [text](#text)                  | `string`                                                                                                            | Optional   |                                                                                                            |
| [heading](#heading)            | `HeadingLevel`                                                                                                      | Optional   | `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`, `TITLE`                      |
| [border](#border)              | `IBorderOptions`                                                                                                    | Optional   | `top`, `bottom`, `left`, `right`. Each of these are of type IBorderPropertyOptions. Click here for Example |
| [spacing](#spacing)            | `ISpacingProperties`                                                                                                | Optional   | See below for ISpacingProperties                                                                           |
| [outlineLevel](#outline-level) | `number`                                                                                                            | Optional   |                                                                                                            |
| alignment                      | `AlignmentType`                                                                                                     | Optional   |                                                                                                            |
| heading                        | `HeadingLevel`                                                                                                      | Optional   |                                                                                                            |
| bidirectional                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| thematicBreak                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| pageBreakBefore                | `boolean`                                                                                                           | Optional   |                                                                                                            |
| contextualSpacing              | `boolean`                                                                                                           | Optional   |                                                                                                            |
| indent                         | `IIndentAttributesProperties`                                                                                       | Optional   |                                                                                                            |
| keepLines                      | `boolean`                                                                                                           | Optional   |                                                                                                            |
| keepNext                       | `boolean`                                                                                                           | Optional   |                                                                                                            |
| children                       | `(TextRun or ImageRun or Hyperlink)[]`                                                                            | Optional   |                                                                                                            |
| style                          | `string`                                                                                                            | Optional   |                                                                                                            |
| [tabStop](usage/tab-stops)     | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional   |                                                                                                            |
| [bullet](usage/bullet-points)  | `{ level: number }`                                                                                                 | Optional   |                                                                                                            |
| [numbering](usage/numbering)   | `{ num: ConcreteNumbering; level: number; custom?: boolean }`                                                       | Optional   |                                                                                                            |
| [widowControl](#widow-control) | `boolean`                                                                                                           | Optional   |                                                                                                            |
| [frame](usage/text-frames.md)  | `IFrameOptions`                                                                                                     | Optional   |                                                                                                            |

## Text

This is the text in a paragraph. You can also add text by using the `Paragraph` shorthand (mentioned above) or adding `children`.

**Example:**

```ts
const paragraph = new Paragraph({
    text: "Hello World",
});
```

## Heading

**Example:**

Setting a Heading 1 paragraph with "Hello World" as it's text:

```ts
const paragraph = new Paragraph({
    text: "Hello World",
    heading: HeadingLevel.HEADING_1,
});
```

## Border

Add borders to a `Paragraph`. Good for making the `Paragraph` stand out

#### IBorderPropertyOptions

`top`, `bottom`, `left`, `right` of the border

| Property | Type     | Notes    |
| -------- | -------- | -------- |
| color    | `string` | Required |
| space    | `number` | Required |
| value    | `string` | Required |
| size     | `number` | Required |

**Example:**

Add border on the top and the bottom of the paragraph

```ts
const paragraph = new Paragraph({
    text: "I have borders on my top and bottom sides!",
    border: {
        top: {
            color: "auto",
            space: 1,
            value: "single",
            size: 6,
        },
        bottom: {
            color: "auto",
            space: 1,
            value: "single",
            size: 6,
        },
    },
});
```

## Shading

Add color to an entire paragraph block<commit_msg>docs: Fix property name accuracy in describing paragraph borders<commit_after># Paragraph

> Everything (text, images, graphs etc) in OpenXML is organized in paragraphs.

!> Paragraphs requires an understanding of [Sections](usage/sections.md).

You can create `Paragraphs` in the following ways:

### Shorthand

```ts
import { Paragraph } from "docx";

const paragraph = new Paragraph("Short hand Hello World");
```

### Children Method

This method is useful for adding different [text](usage/text.md) with different styles, [symbols](usage/symbols.md), or adding [images](usage/images.md) inline.

```ts
const paragraph = new Paragraph({
    children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World"), new SymbolRun("F071")],
});
```

### Explicit

```ts
const paragraph = new Paragraph({
    text: "Short hand notation for adding text.",
});
```

After you create the paragraph, you must add the paragraph into a `section`:

```ts
const doc = new Document({
    sections: [{
        children: [paragraph],
    }];
});
```

Or the preferred convention, define the paragraph inside the section and remove the usage of variables:

```ts
const doc = new Document({
    sections: [{
        children: [
            new Paragraph({
                children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")],
            }),
        ],
    }];
});
```

## Options

This is the list of options for a paragraph. A detailed explanation is below:

| Property                       | Type                                                                                                                | Mandatory? | Possible Values                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| [text](#text)                  | `string`                                                                                                            | Optional   |                                                                                                            |
| [heading](#heading)            | `HeadingLevel`                                                                                                      | Optional   | `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`, `TITLE`                      |
| [border](#border)              | `IBorderOptions`                                                                                                    | Optional   | `top`, `bottom`, `left`, `right`. Each of these are of type IBorderPropertyOptions. Click here for Example |
| [spacing](#spacing)            | `ISpacingProperties`                                                                                                | Optional   | See below for ISpacingProperties                                                                           |
| [outlineLevel](#outline-level) | `number`                                                                                                            | Optional   |                                                                                                            |
| alignment                      | `AlignmentType`                                                                                                     | Optional   |                                                                                                            |
| heading                        | `HeadingLevel`                                                                                                      | Optional   |                                                                                                            |
| bidirectional                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| thematicBreak                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| pageBreakBefore                | `boolean`                                                                                                           | Optional   |                                                                                                            |
| contextualSpacing              | `boolean`                                                                                                           | Optional   |                                                                                                            |
| indent                         | `IIndentAttributesProperties`                                                                                       | Optional   |                                                                                                            |
| keepLines                      | `boolean`                                                                                                           | Optional   |                                                                                                            |
| keepNext                       | `boolean`                                                                                                           | Optional   |                                                                                                            |
| children                       | `(TextRun or ImageRun or Hyperlink)[]`                                                                            | Optional   |                                                                                                            |
| style                          | `string`                                                                                                            | Optional   |                                                                                                            |
| [tabStop](usage/tab-stops)     | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional   |                                                                                                            |
| [bullet](usage/bullet-points)  | `{ level: number }`                                                                                                 | Optional   |                                                                                                            |
| [numbering](usage/numbering)   | `{ num: ConcreteNumbering; level: number; custom?: boolean }`                                                       | Optional   |                                                                                                            |
| [widowControl](#widow-control) | `boolean`                                                                                                           | Optional   |                                                                                                            |
| [frame](usage/text-frames.md)  | `IFrameOptions`                                                                                                     | Optional   |                                                                                                            |

## Text

This is the text in a paragraph. You can also add text by using the `Paragraph` shorthand (mentioned above) or adding `children`.

**Example:**

```ts
const paragraph = new Paragraph({
    text: "<NAME>",
});
```

## Heading

**Example:**

Setting a Heading 1 paragraph with "Hello World" as it's text:

```ts
const paragraph = new Paragraph({
    text: "<NAME>",
    heading: HeadingLevel.HEADING_1,
});
```

## Border

Add borders to a `Paragraph`. Good for making the `Paragraph` stand out

#### IBorderPropertyOptions

`top`, `bottom`, `left`, `right` of the border

| Property | Type     | Notes    |
| -------- | -------- | -------- |
| color    | `string` | Required |
| space    | `number` | Required |
| style    | `string` | Required |
| size     | `number` | Required |

**Example:**

Add border on the top and the bottom of the paragraph

```ts
const paragraph = new Paragraph({
    text: "I have borders on my top and bottom sides!",
    border: {
        top: {
            color: "auto",
            space: 1,
            style: "single",
            size: 6,
        },
        bottom: {
            color: "auto",
            space: 1,
            style: "single",
            size: 6,
        },
    },
});
```

## Shading

Add color to an entire paragraph block
{'fraction_non_alphanumeric': 0.1025428870869877, 'fraction_numerical': 0.0016548072149594572, 'mean_word_length': 0.572010751755831, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 380, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3478957', 'n_tokens_mistral': 2734, 'n_tokens_neox': 2611, 'n_words': 833}