1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
# Adding Tables of Data
Arrange information into rows and columns.
## Overview
To add a table to your documentation, start a new paragraph and add the following required elements, each on its own line:
* A table header, with the heading text of each column, separated by pipes (`|`)
* A separator row, with at least 3 hyphens (`-`) for each column, separated by pipes
* One or more rows of table cells, separating each cell of formatted content by a pipe
```md
Sloth speed | Description
------------ | -------------------------------------
`slow` | Moves slightly faster than a snail
`medium` | Moves at an average speed
`fast` | Moves faster than a hare
`supersonic` | Moves faster than the speed of sound
```
The example markup above defines the table that's shown below. Each column is automatically sized to fit its widest cell and the table is only as wide as the sum of its columns.
Sloth speed | Description
------------ | -------------------------------------
`slow` | Moves slightly faster than a snail
`medium` | Moves at an average speed
`fast` | Moves faster than a hare
`supersonic` | Moves faster than the speed of sound
It's not necessary to pad the cells to align the column separators (`|`). However, it may make your table _markup_ easier to read, especially for large or complex tables.
The same table could have been defined like below. All other examples will uses padded cells for readability.
```md
Sloth speed|Description
---|---
`slow`|Moves slightly faster than a snail
`medium`|Moves at an average speed
`fast`|Moves faster than a hare
`supersonic`|Moves faster than the speed of sound
```
You can add leading and/or trailing pipes (`|`) if you find that table markup easier to read. This doesn't affect the rendered table on the page. The leading and trailing pipes _can_ be applied inconsistently for each row but doing so may make it harder to discern the structure of the table.
```md
| Sloth speed | Description |
| ------------ | ------------------------------------ |
| `slow` | Moves slightly faster than a snail |
| `medium` | Moves at an average speed |
| `fast` | Moves faster than a hare |
| `supersonic` | Moves faster than the speed of sound |
```
The content of a table cell supports the same style attributes as other text and supports links to other content, including symbols. If a table cell's content includes a pipe (`|`) you need to escape the pipe character by preceding it with a backslash
(`\`). For more information about styling text, see [Format Text in Bold, Italics, and Code Voice](doc:formatting-your-documentation-content#Format-Text-in-Bold,-Italics,-and-Code-Voice).
> Note: A table cell can only contain a single line of formatted content. Lists, asides, code blocks, headings, and directives are not supported inside a table cell.
### Aligning content in a column
By default, all table columns align their content to the leading edge. To change the horizontal alignment for a column, modify the table's separator row to add a colon (`:`) around the hyphens (`-`) for that column, either before the hyphens for leading alignment, before _and_ after the hyphens for center alignment, or after the hyphens for trailing alignment.
Leading | Center | Trailing
:------- | :------: | --------:
`:-----` | `:----:` | `-----:`
 |  | 
### Spanning cells across columns
By default, each table cell is one column wide and one row tall. To span a table cell across multiple columns, place two or more column separators (`|`) next to each other after the cell's content. If the spanning cell is the last or only element of a row, you need to add the extra trailing pipe (`|`) for that row, otherwise DocC will interpret the row as having an additional empty cell at the end. For example:
@Row {
@Column {
```md
First | Second | Third |
----- | ------ | ----- |
One || Two |
Three | Four ||
Five |||
```
}
@Column {
First | Second | Third |
----- | ------ | ----- |
One || Two |
Three | Four ||
Five |||
}
}
> Tip: You may find it easier to discern the structure of your table from its markup if you use trailing pipes consistently when spanning cells.
A spanning cells determines its horizontal alignment from the left-most column that it spans. Going from left to right in the example below:
- Cells "One" and "Five" uses leading alignment because they both span the first column
- Cell "Four" uses center alignment because it spans the second column
- Cell "Two" uses trailing alignment because it spans the third column
@Row {
@Column {
```md
Leading | Center | Trailing |
------: | :----: | :------- |
One || Two |
Three | Four ||
Five |||
```
}
@Column {
Leading | Center | Trailing |
:------ | :----: | -------: |
One || Two |
Three | Four ||
Five |||
}
}
### Spanning cells across rows
To span a table cell across multiple rows, write the cell's content in the first row and a single caret (`^`) in one or more cells below it. For example:
@Row {
@Column {
```md
First | Second | Third | Fourth
----- | ------ | ----- | ------
One | Two | Three | Four
^ | Five | ^ | Six
Seven | ^ | ^ | Eight
```
}
@Column {
First | Second | Third | Fourth
----- | ------ | ----- | ------
One | Two | Three | Four
^ | Five | ^ | Six
Seven | ^ | ^ | Eight
}
}
A table cell can span both columns and rows by combining the syntax for both. For example:
@Row {
@Column {
```md
First | Second | Third
----- | ------ | -----
One || Two
^ || Three
```
}
@Column {
First | Second | Third
----- | ------ | -----
One || Two
^ || Three
}
}
<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
|
