diff --git a/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/html5-demo.mp4 b/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/html5-demo.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..7738f947269726bb270fa08576ed835eeb7a4d6f Binary files /dev/null and b/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/html5-demo.mp4 differ diff --git a/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md b/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md new file mode 100644 index 0000000000000000000000000000000000000000..e8322e5b622e9969e357815b9dcaeac16124ed53 --- /dev/null +++ b/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md @@ -0,0 +1,1316 @@ +--- +layout: markdown_page +title: "Markdown Guide" +--- + +Technical Writing Handbook - Markdown Kramdown Style Guide for [about.GitLab.com] + +---- + +## On this page +{:.no_toc} + +- TOC +{:toc} + +---- + +## Markdown Style Guide for about.GitLab.com + +This website was generated by [Middleman], a blog-aware Static Site Generator ([SSG]) widely used by web developers. +[Markup language] is part of the structure of any SSG. It is a system to write documents making them somehow +syntactically distinguishable from text. [Lightweight markup languages] have a simplified and unobtrusive syntax, +designed to be easily written within any text editor. That's what we use to write our content. The majority of +SSGs use markdown engines for this purpose. Read through our blog post on [Modern Static Site Generators][ssgs-post] +to understand how they work. + +For [about.GitLab.com], we use [Kramdown], which is an advanced markdown engine with a lot of interesting features that +most of the other engines don't have. + +If you never have written a single line in markdown markup, don't worry, it's easy to learn and even easier to use. You'll +probably be surprised how handy it is once you get used to it. And you'll miss it whenever the tech you're using doesn't support +markdown. + +In most of GitLab text areas you'll find markdown support. Not all of them run with Kramdown, so the markup will not +behave equally "GitLabwide". For **GitLab.com**, **GitLab CE** and **GitLab EE** text areas, the markdown engine is currently +[Redcarpet]. Here you can find the [markdown style guide][gitlab-markdown] for them. + +This guide has been made to make it easier for everyone to use Kramdown features and save a lot of time writing content for +[about.GitLab.com], including handbook pages, website pages, blog posts and everything else within the project [www-GitLab-com]. + +There are different possible syntaxes for most of the markups described below, but this guide is to be considered the +standard for about.GitLab.com. + +---- + +## Headings + +```md +## Heading h2 + +### Heading h3 + +#### Heading h4 +``` + +{::options parse_block_html="true" /} + +
+ +**Output** +{: .panel-heading} + +
+## Heading h2 +{:.no_toc style="margin-top:0"} + +### Heading h3 +{:.no_toc} + +#### Heading h4 +{:.no_toc} +
+
+ +Notes: + +- Usually we don't use `h1` headings, as they already are displayed on every page as titles. +- Always leave a blank space between the hash `#` and the text next to it, otherwise it won't render properly. + +---- + +## Paragraphs, breaks and horizontal lines + +Regular paragraphs are obtained by just writing text lines. If you hit enter between two lines, +both lines will be joined into a single paragraph. +But, if you leave a blank line between them, they will split in two paragraphs. + +### Regular paragraphs and automatic join + +```md +This text is a paragraph. +This won't be another paragraph, it will join the line above it. + +This will be another paragraph, as it has a blank line above it. +``` + +
+ +**Output** +{: .panel-heading} + +
+ +This text is a paragraph. +This won't be another paragraph, it will join the line above it. + +This will be another paragraph, as it has a blank line above it. + +
+
+ +_**Note:** We usually break the lines within paragraphs to facilitate reviews. Do not leave blank spaces after the last +word of the line broken within a paragraph, unless you want it to be intentionally broken with a `
`._ +{: .note} + + + +### Additional breaks + +In case you need an additional break (or some extra space between lines), you can simply use the HTML break tag `
`, +leaving blank lines above and below it: + +```html +Text A + +
+ +Text B +``` + +
+ +**Output** +{: .panel-heading} + +
+ +Text A + +
+ +Text B + +
+
+ +### Horizontal lines + +A sequence of three or more dashes will produce a horizontal line, but let's use always **4** for standard. Leave blank +lines after and before it: + +```html +Text + +---- + +Text +``` + +
+ +**Output** +{: .panel-heading} + +
+ +Text + +---- + +Text + +
+
+ +---- + +## Emphasis: bold and italic + +To display bold or italic text, wrap it into stars or underlines: + +```md +This is **bold** and this is _italic_. +``` + +
+ +**Output** +{: .panel-heading} + + +
+ +This is **bold** and this is _italic_. + +
+
+ +---- + +## Links + +There are a few different ways to display links with markdown markup, but +to keep some standards, let's try to use the following options only. + +Place the identifiers at the end of the file, arrange them in alphabetical order. +You can group them in different categories, if that's the case. Check +[this post][ssgs-post-raw] for reference. It's important to organize the links in certain +order to be easy and quick to find them for both the author and the reviewers. + + +```md +[Text to display][identifier] will display a link. + +[Another text][another-identifier] will do the same. Hover the mouse over it to see the title. + +[This link] will do the same as well. It works as the identifier itself. + + works too. Must be used for explicit links. + +... (page content) ... + + + +[another-identifier]: https://example.com "This example has a title" +[identifier]: http://example1.com +[this link]: http://example2.com + +``` + +
+ +**Output** +{: .panel-heading} + +
+ +[Text to display][identifier] will display a link. + +[Another text][another-identifier] will do the same. Hover the mouse over it to see the title. + +[This link] will do the same as well. It works as the identifier itself. + + works too. Must be used for explicit links. + +... (page content) ... + + + +[another-identifier]: https://example.com "This example has a title" +[identifier]: http://example1.com +[this link]: http://example2.com + +
+
+ +Important notes: + +- Identifiers **are not** case sensitive. They can be single words as `[link]` or `[multiple words too]`. +- Avoid using other markup syntax for links. Definitely avoid adding the URL in-line, as +in `[link](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/2373#note_12594349)`. +This syntax works perfectly, but breaks the reading flow, deviating the attention of the reviewer. +Also, it may cause repetition of the same link through the document. +- Don't take it as a restrictive rule, but [avoid using meaningless texts for links][handbook-writing] as "this article" +or "read here". For these examples, it would be better using the article's title (for the first) and +the documentation's subject, for the latter. + +---- + +## Lists + +Both ordered and unordered lists are very straight-forward to produce. There are a few ways +to produce the same results, but let's stick with the following, again, to maintain +some standards. + +Always use **3** blank spaces to indent a nested list (to create sub items). + +Tip: don't leave blank lines between the items, unless you have a reason to do so. + +### Ordered lists + +Ordered lists are pretty easy to create. Couldn't be more intuitive: + +```md +1. Item one + 1. Sub item one + 2. Sub item two + 3. Sub item three +2. Item two +``` + +
+ +**Output** +{: .panel-heading} + + +
+ +1. Item one + 1. Sub item one + 2. Sub item two + 3. Sub item three +2. Item two + +
+
+ +To be practical and avoid errors on the numbers, use "1" for all the items. The markdwon engine will output them +in the correct order. + +```md +1. Item one + 1. Sub item one + 1. Sub item two +1. Item two +1. Item three +``` + +
+ +**Output** +{: .panel-heading} + + +
+ +1. Item one + 1. Sub item one + 2. Sub item two +1. Item two +1. Item three + +
+
+ + +### Unordered lists + +Unordered lists are very easy to create too: + +```md +- Item 1 +- Item 2 +- Item 3 + - Sub item 1 + - Sub item 2 +- Item 4 +``` + +
+ +**Output** +{: .panel-heading} + + +
+ +- Item 1 +- Item 2 +- Item 3 + - Sub item 1 + - Sub item 2 +- Item 4 + +
+
+ +### Split lists + +Let's say, for some reason, you want to split a list in different parts. To do that, use the +markup `^` to indicate the end of a list and the beginning of the next: + +```md +- list one - item 1 +- list one - item 2 + - sub item 1 + - sub item 2 +- list one - item 3 +^ +- list two - item A +- list two - item A +^ +- list three - item _i_ +- list three - item _ii_ +``` + +
+ +**Output** +{: .panel-heading} + + +
+ +- list one - item 1 +- list one - item 2 + - sub item 1 + - sub item 2 +- list one - item 3 +^ +- list two - item A +- list two - item A +^ +- list three - item _i_ +- list three - item _ii_ + +
+
+ +---- + +## Images + +To insert images to your markdown file, use the markup `![ALT](/path/image.ext)`. The path can either +be relative to the website, or a full URL for an external image. The supported formats are +`.png`, `.jpg`, `.gif`. You might be able to use some `.svg` files too, depending on its structure. + +```md +![An awesome example image](/images/path/to/folder/image.png "Image Title") +``` + +You can also use an identifier, as we do for [links](#links): + +```md +![An awesome example image][identifier] +``` + +If you want to add a caption to your image, it's easily achieved with: + +```md +![An awesome example image](/images/path/to/folder/image.png)*My caption* +``` + +For clickable images, simply wrap the image markup into a [link markup](#links): + +```md +[![An awesome example image](/images/path/to/folder/image.png "Hello World")*My caption*][about.gitlab.com] +``` + +
+ +**Output** +{: .panel-heading} + +
+ +[![An awesome example image](/images/about-gitlab-com.png "Hello World")*My caption*][about.gitlab.com] + +
+
+ +Notes: + +- All images must be placed [under `/source/images/`][source-img], in an appropriate directory. Only screenshots +and public domain images are permitted. +- The text inside the square brackets is an image attribute called `ALT`, which stands for _alternative text_. +It [must not be left empty][img-seo], but contain something to describe that image. `ALT` is useful for +[visually impaired internauts][visually-impaired], for SEO, and it is displayed when, for some reason, that image is not loaded by the browser. +- For the same reasons, the image must contain a name related to it. Example: instead of `image-01.jpg`, +name it `black-dog.jpg`, if it's a photo of a black dog. +- It's also recommendable adding an image title, as the "Hello World" exemplified above. + +---- + +## Videos + + + +There are two ways of displaying videos: within HTML5 `