From 7da80b2d36adc30964423042e956ef880a2650f9 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Fri, 19 Jul 2019 02:20:32 +0000 Subject: Update numbered lists for docs standards Ensure that all numbered lists use only 1. and no other numbers. Also ensure that numbered lists use proper spacing. --- doc/development/documentation/styleguide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/development/documentation/styleguide.md') diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 1ca965f8ae9..ccf1deefd91 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -44,9 +44,9 @@ Include any media types/sources if the content is relevant to readers. You can f In the software industry, it is a best practice to organize documentatioin in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): 1. Tutorials -2. How-to guides -3. Explanation -4. Reference (for example, a glossary) +1. How-to guides +1. Explanation +1. Reference (for example, a glossary) At GitLab, we have so many product changes in our monthly releases that we can't afford to continually update multiple types of information. If we have multiple types, the information will become outdated. Therefore, we have a [single template](structure.md) for documentation. @@ -142,9 +142,9 @@ The table below shows what kind of documentation goes where. ### Working with directories and files 1. When you create a new directory, always start with an `index.md` file. - Do not use another file name and **do not** create `README.md` files. + Do not use another file name and **do not** create `README.md` files. 1. **Do not** use special characters and spaces, or capital letters in file names, - directory names, branch names, and anything that generates a path. + directory names, branch names, and anything that generates a path. 1. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (`-`). For example, a proper naming would be `import_projects_from_github.md`. The same rule -- cgit v1.2.1 From d0a60a7525459c13b5d0bd125bfdf518baa6c3be Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Mon, 22 Jul 2019 06:03:12 +0000 Subject: Add info about mdl to documentation --- doc/development/documentation/styleguide.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc/development/documentation/styleguide.md') diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index ccf1deefd91..36ffc02644e 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -107,6 +107,22 @@ Hard-coded HTML is valid, although it's discouraged to be used while we have `/h - Special styling is required. - Reviewed and approved by a technical writer. +### Markdown Rules + +GitLab ensures that the Markdown used across all documentation is consistent, as +well as easy to review and maintain, by testing documentation changes with +[Markdownlint (mdl)](https://github.com/markdownlint/markdownlint). This lint test +checks many common problems with Markdown, and fails when any document has an issue +with Markdown formatting that may cause the page to render incorrectly within GitLab. +It will also fail when a document is using non-standard Markdown (which may render +correctly, but is not the current standard in GitLab documentation). + +Each formatting issue that mdl checks has an associated [rule](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md), +and the rules that are currently enabled for GitLab documentation are listed in the +[`.mdlrc.style`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style) file. +Configuration options are set in the [`.mdlrc`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.mdlrc.style) +file. + ## Structure ### Organize by topic, not by type -- cgit v1.2.1 From 0f7d8c04219a5631d48a2eff59d4a5daa881787f Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Thu, 25 Jul 2019 22:49:13 +0000 Subject: Update links to relative Following the single docs codebase change, all internal links should be relative. Also cleans up one table --- doc/development/documentation/styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/development/documentation/styleguide.md') diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 36ffc02644e..dd798777c12 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1092,6 +1092,6 @@ curl --request PUT --header "PRIVATE-TOKEN: " --data "domain_ [cURL]: http://curl.haxx.se/ "cURL website" [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html -[gfm]: https://docs.gitlab.com/ce/user/markdown.html#newlines "GitLab flavored markdown documentation" +[gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation" [ce-1242]: https://gitlab.com/gitlab-org/gitlab-ce/issues/1242 [doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation" -- cgit v1.2.1 From cc76259e8d0101c8f2a890a7f6dcf41ec1c58e18 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 31 Jul 2019 08:28:51 +0000 Subject: Fix whitespace in ci docs Many code blocks are 4spaced, and they render in GitLab without coloring as a result, even though they are fenced with a language label. If in a list, other items will render as being in a code block too, even if not meant to. This fixes all these issues for most docs in /development, and cleans up other whitespace issues too --- doc/development/documentation/styleguide.md | 87 ++++++++++++++--------------- 1 file changed, 43 insertions(+), 44 deletions(-) (limited to 'doc/development/documentation/styleguide.md') diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index dd798777c12..e84d65f424e 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -36,8 +36,8 @@ For the Troubleshooting sections, people in GitLab Support can merge additions t Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. - - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. - - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. +- If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. +- Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. ### No special types @@ -237,14 +237,14 @@ Do not include the same information in multiple places. [Link to a SSOT instead. - Use sentence case for titles, headings, labels, menu items, and buttons. - Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example: - ```md - ## Header + ```md + ## Header - Paragraph. + Paragraph. - - List item 1 - - List item 2 - ``` + - List item 1 + - List item 2 + ``` ### Tables overlapping the TOC @@ -303,12 +303,12 @@ Check specific punctuation rules for [list items](#list-items) below. - Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period. - Separate list items from explanatory text with a colon (`:`). For example: - ```md - The list is as follows: + ```md + The list is as follows: - - First item: this explains the first item. - - Second item: this explains the second item. - ``` + - First item: this explains the first item. + - Second item: this explains the second item. + ``` **Examples:** @@ -520,16 +520,16 @@ To embed a video, follow the instructions below and make sure you have your MR reviewed and approved by a technical writer. 1. Copy the code below and paste it into your markdown file. - Leave a blank line above and below it. Do NOT edit the code - (don't remove or add any spaces, etc). + Leave a blank line above and below it. Do NOT edit the code + (don't remove or add any spaces, etc). 1. On YouTube, visit the video URL you want to display. Copy - the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) - and replace the video title and link in the line under `
`. + the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) + and replace the video title and link in the line under `
`. 1. On YouTube, click **Share**, then **Embed**. 1. Copy the `