For Discussion: Standardize Markdown Tables
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:
| Item 1 | Item 2 | Item 3 |
|--------|--------|--------|
| Data1 | Data 2 | Data3 |The tool Evan found that allows some padding adjustment: "limitLastColumnPadding: Do not pad the last column to more than your editor's preferredLineLength setting.; (my LineLength is set to 80)
| 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:
| 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.
| 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. |