Pre-format handbook pages to adhere with commonmark + GFM conventions
Let’s pre-format the Handbook pages to mitigate the amount of changes and potential errors introduced by Static Site Editor’s WYSIWYG mode .
Instructions
Follow these instructions to pre-format one or more handbook pages:
Markdown formatter and linter tool
Use the markdown linter to detect parts of a markdown document that do not comply with the Handbook’s markdown conventions. This linter is pre-configured and ready to use. This will help you to quickly spot places that needs fixing:
yarn lint-md sites/handbook/source/handbook/about
If you add the -o
flag, the lint-md
command will format the target files with consistent styles:
yarn lint-md sites/handbook/source/handbook/about -o
NOTICE: The downside of this automatic formatting tool is that it breaks Kramdown features like attribute definitions used for Table of Contents. See the Manual Actions section for workarounds.
My recommendation is to run the lint-md
command with the -o
flag first, and then run it again in Lint mode to detect which parts of the document still need manual work.
Manual actions
Besides the automatic fixes performed by the formatter tool, you should be aware of the following issues that should be fixed manually:
Ordered nested lists indented with 2 spaces
The formatter as well as the Static Site Editor will break ordered nested lists indented with only two spaces. You will have to fix this problem manually by adding two extra spaces in the indentation:
<!-- replace this with this -->
1. item 1
1. item 2
<!-- with this -->
1. item 1
1. item 2
HTML blocks with spaces
HTML blocks should not be surrounded by empty lines or otherwise a CommonMark parser will treat it as a code block:
<table>
<!-- The empty line below will break this HTML block so remove it -->
<tr>
<td height="4" class="tg-xkfo" colspan="1"></td>
<td height="4" class="tg-xkfo" colspan="8">UseCase</td>
<td height="4" class="tg-xkfo" colspan="1">Industry/ Vertical</td>
</tr>
</table></div>
Editors like Visual Studio will also highlight broken HTML blocks:
Do not wrap links in bold or emphasis formats
Change [**GitLab**](https://gitlab.com) to **[GitLab](https://gitlab.com)**
Kramdown TOC
Change this:
## On this page
{:.no_toc .hidden-md .hidden-lg}
- TOC
{:toc .hidden-md .hidden-lg}
With this:
## On this page
{:.no_toc .hidden-md .hidden-lg}
- TOC
{:toc .hidden-md .hidden-lg}
Merge Request template
If you don’t want to write over and over again the description for each formatting MR, you can use this template that explains what these MRs are about:
MR title: Pre-format [/handbook/about] section
MR description:
This change is part of the effort lead by the Static Site Editor team to apply a consistent Markdown styles to handbook pages. This MR focuses on formatting the [insert your section here] of the Handbook.
See more information in #8892
Formatted pages
Add in this list the handbook sections you will pre-format:
-
sites/handbook/source/handbook/about
!60849 (merged) - @ealcantara -
sites/handbook/source/handbook/acquisitions
!60854 (merged) @ealcantara -
sites/handbook/source/handbook/alliances
!60937 (merged) @ealcantara -
sites/handbook/source/handbook/anti-harrasment
!61211 (merged) @ealcantara -
sites/handbook/source/handbook/being-a-public-company
!61211 (merged) @ealcantara -
sites/handbook/source/handbook/board-meetings
!61211 (merged) @ealcantara -
sites/handbook/source/handbook/business-ops
!61635 (merged) @ericschurter