Tables in markdown are implemented in a dozen different ways within our docs. We should settle on a firm set of rules so that they all look the same, are easy to edit/review, and always render properly. We should also use rules that can be enforced by our editors, so it can be done automatically. My proposal: - Pipes on both sides - one space padding, always - all columns, except last, should align with column titles - last column should not be full of wasted whitespace, so limit padding somehow. Examples: ```md | Item 1 | Item 2 | Item 3 | |--------|--------|--------| | Data1 | Data 2 | Data3 | ``` The [tool Evan found that allows some padding adjustment](https://marketplace.visualstudio.com/items?itemName=fcrespo82.markdown-table-formatter&ssr=false#overview): "limitLastColumnPadding: Do not pad the last column to more than your editor's preferredLineLength setting.; (my LineLength is set to 80) ```md | Item 1 | Item 2 | Item 3 | |---------|---------|----------------------------------------------------------| | Data1 | Data 2 | Data3 is very long so the column stretches, but the other items shouldn't pad more than 80 | | Data 1b | Data 2b | Data3b has max 80 char padding. | ``` Preferably, I would only pad as far as the last column title, but could not find a tool that allows this: ```md | Item 1 | Item 2 | Item 3 is a little longer than before | |---------|---------|---------------------------------------| | Data1 | Data 2 | Data3 is very long so the column stretches, but the other items shouldn't pad more than 80 | | Data 1b | Data 2b | Data3b pads just to title | ``` If the last title is short, then it's fine for everything to have no padding at all in the last column, IMHO. ```md | Item 1 | Item 2 | Item 3 | |---------|---------|--------| | Data1 | Data 2 | Data3 is very long so the column stretches, but the other items shouldn't pad more than 80 | | Data 1b | Data 2b | Data3b is this long | | Data 1c | Data 2c | Data3c is this looooooooooooooong | | Data 1d | Data 2d | Data3d is short| ``` ## UPDATE: Voting Options To make it easier to decide, here are the options, and please comment on which you prefer, and feel free to add more options. I can also write in the style guide that the most popular option is the `recommendation`, NOT a rule, if desired. ### Option 1 All columns except last should be aligned, if possible. Right remains "ragged". ``` | Keyboard Shortcut | Description | | ------------------------------- | ----------- | | <kbd>?</kbd> | Show/hide shortcut reference sheet. | | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to the activity feed page. | | <kbd>Shift</kbd> + <kbd>p</kbd> | Go to the projects page. | | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to the issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to the merge requests page .| | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to the todos page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | | <kbd>s</kbd> | Put cursor in the issues/merge requests search. | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field in a thread, and you must have at least one comment in the thread. | ``` ### Option 2 Columns aligned up to the max line length (80 chars). We can decide on titles (align or not), if this option is popular. ``` | Keyboard Shortcut | Description | | ------------------------------- | ----------- | | <kbd>?</kbd> | Show/hide shortcut reference sheet. | | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to the activity feed page. | | <kbd>Shift</kbd> + <kbd>p</kbd> | Go to the projects page. | | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to the issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to the merge requests page . | | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to the todos page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | | <kbd>s</kbd> | Put cursor in the issues/merge requests search. | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field in a thread, and you must have at least one comment in the thread. | ``` ### Option 3 All columns aligned all the time. ``` | Keyboard Shortcut | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | <kbd>?</kbd> | Show/hide shortcut reference sheet. | | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to the activity feed page. | | <kbd>Shift</kbd> + <kbd>p</kbd> | Go to the projects page. | | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to the issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to the merge requests page . | | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to the todos page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | | <kbd>s</kbd> | Put cursor in the issues/merge requests search. | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field in a thread, and you must have at least one comment in the thread. | ``` ### Option 4 No extra whitespace anywhere. ``` | Keyboard Shortcut | Description | | ----------------- | ----------- | | <kbd>?</kbd> | Show/hide shortcut reference sheet. | | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to the activity feed page. | | <kbd>Shift</kbd> + <kbd>p</kbd> | Go to the projects page. | | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to the issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to the merge requests page. | | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to the todos page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | | <kbd>s</kbd> | Put cursor in the issues/merge requests search. | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field in a thread, and you must have at least one comment in the thread. | ```