|
| 1 | +# Adding Tables of Data |
| 2 | + |
| 3 | +Arrange information into rows and columns. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +To add a table to your documentation, start a new paragraph and add the following required elements, each on its own line: |
| 8 | + |
| 9 | +* A table header, with the heading text of each column, separated by pipes (`|`) |
| 10 | +* A separator row, with at least 3 hyphens (`-`) for each column, separated by pipes |
| 11 | +* One or more rows of table cells, separating each cell of formatted content by a pipe |
| 12 | + |
| 13 | +```md |
| 14 | +Sloth speed | Description |
| 15 | +------------ | ------------------------------------- |
| 16 | +`slow` | Moves slightly faster than a snail |
| 17 | +`medium` | Moves at an average speed |
| 18 | +`fast` | Moves faster than a hare |
| 19 | +`supersonic` | Moves faster than the speed of sound |
| 20 | +``` |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +Sloth speed | Description |
| 25 | +------------ | ------------------------------------- |
| 26 | +`slow` | Moves slightly faster than a snail |
| 27 | +`medium` | Moves at an average speed |
| 28 | +`fast` | Moves faster than a hare |
| 29 | +`supersonic` | Moves faster than the speed of sound |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +The same table could have been defined like below. All other examples will uses padded cells for readability. |
| 34 | + |
| 35 | +```md |
| 36 | +Sloth speed|Description |
| 37 | +---|--- |
| 38 | +`slow`|Moves slightly faster than a snail |
| 39 | +`medium`|Moves at an average speed |
| 40 | +`fast`|Moves faster than a hare |
| 41 | +`supersonic`|Moves faster than the speed of sound |
| 42 | +``` |
| 43 | + |
| 44 | +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. |
| 45 | + |
| 46 | +```md |
| 47 | +| Sloth speed | Description | |
| 48 | +| ------------ | ------------------------------------ | |
| 49 | +| `slow` | Moves slightly faster than a snail | |
| 50 | +| `medium` | Moves at an average speed | |
| 51 | +| `fast` | Moves faster than a hare | |
| 52 | +| `supersonic` | Moves faster than the speed of sound | |
| 53 | +``` |
| 54 | + |
| 55 | +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 |
| 56 | +(`\`). 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). |
| 57 | + |
| 58 | +> 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. |
| 59 | +
|
| 60 | +### Aligning content in a column |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +Leading | Center | Trailing |
| 65 | +:------- | :------: | --------: |
| 66 | +`:-----` | `:----:` | `-----:` |
| 67 | + |  |  |
| 68 | + |
| 69 | +### Spanning cells across columns |
| 70 | + |
| 71 | +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: |
| 72 | + |
| 73 | +@Row { |
| 74 | + @Column { |
| 75 | + ```md |
| 76 | + First | Second | Third | |
| 77 | + ----- | ------ | ----- | |
| 78 | + One || Two | |
| 79 | + Three | Four || |
| 80 | + Five ||| |
| 81 | + ``` |
| 82 | + } |
| 83 | + @Column { |
| 84 | + First | Second | Third | |
| 85 | + ----- | ------ | ----- | |
| 86 | + One || Two | |
| 87 | + Three | Four || |
| 88 | + Five ||| |
| 89 | + } |
| 90 | +} |
| 91 | + |
| 92 | +> 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. |
| 93 | +
|
| 94 | +A spanning cells determines its horizontal alignment from the left-most column that it spans. Going from left to right in the example below: |
| 95 | + |
| 96 | + - Cells "One" and "Five" uses leading alignment because they both span the first column |
| 97 | + - Cell "Four" uses center alignment because it spans the second column |
| 98 | + - Cell "Two" uses trailing alignment because it spans the third column |
| 99 | + |
| 100 | +@Row { |
| 101 | + @Column { |
| 102 | + ```md |
| 103 | + Leading | Center | Trailing | |
| 104 | + ------: | :----: | :------- | |
| 105 | + One || Two | |
| 106 | + Three | Four || |
| 107 | + Five ||| |
| 108 | + ``` |
| 109 | + } |
| 110 | + @Column { |
| 111 | + Leading | Center | Trailing | |
| 112 | + :------ | :----: | -------: | |
| 113 | + One || Two | |
| 114 | + Three | Four || |
| 115 | + Five ||| |
| 116 | + } |
| 117 | +} |
| 118 | + |
| 119 | +### Spanning cells across rows |
| 120 | + |
| 121 | +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: |
| 122 | + |
| 123 | +@Row { |
| 124 | + @Column { |
| 125 | + ```md |
| 126 | + First | Second | Third | Fourth |
| 127 | + ----- | ------ | ----- | ------ |
| 128 | + One | Two | Three | Four |
| 129 | + ^ | Five | ^ | Six |
| 130 | + Seven | ^ | ^ | Eight |
| 131 | + ``` |
| 132 | + } |
| 133 | + @Column { |
| 134 | + First | Second | Third | Fourth |
| 135 | + ----- | ------ | ----- | ------ |
| 136 | + One | Two | Three | Four |
| 137 | + ^ | Five | ^ | Six |
| 138 | + Seven | ^ | ^ | Eight |
| 139 | + } |
| 140 | +} |
| 141 | + |
| 142 | +A table cell can span both columns and rows by combining the syntax for both. For example: |
| 143 | + |
| 144 | +@Row { |
| 145 | + @Column { |
| 146 | + ```md |
| 147 | + First | Second | Third |
| 148 | + ----- | ------ | ----- |
| 149 | + One || Two |
| 150 | + ^ || Three |
| 151 | + ``` |
| 152 | + } |
| 153 | + @Column { |
| 154 | + First | Second | Third |
| 155 | + ----- | ------ | ----- |
| 156 | + One || Two |
| 157 | + ^ || Three |
| 158 | + } |
| 159 | +} |
| 160 | + |
| 161 | +<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. --> |
0 commit comments