Skip to content
Snippets Groups Projects
Commit 3c8f7b11 authored by Marcia Ramos's avatar Marcia Ramos Committed by 🚄 Job van der Voort 🚀
Browse files

Move Technical Writing related handbooks to Product

parent 788eb282
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 2428 additions and 2422 deletions
README.md
+ 2
− 2
View file @ 3c8f7b11
@@ -119,7 +119,7 @@ before publishing, see [**Local development**](#local-development) for
instructions.
 
[Blog Handbook]: https://about.gitlab.com/handbook/marketing/blog/
[mkd-guide]: https://about.gitlab.com/handbook/marketing/developer-relations/technical-writing/markdown-guide/
[mkd-guide]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/
 
### Adding yourself to the team page
 
@@ -312,7 +312,7 @@ follow the steps below:
[press releases]: https://about.gitlab.com/press/releases/
[press category]: https://about.gitlab.com/blog/categories/press
[blog archives]: https://about.gitlab.com/blog/archives.html
[md]: https://about.gitlab.com/handbook/marketing/developer-relations/technical-writing/markdown-guide
[md]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide
 
### Update the features page (under `/features`)
 
data/team.yml
+ 2
− 2
View file @ 3c8f7b11
@@ -909,8 +909,8 @@
twitter: XMDRamos
gitlab: marcia
maintains: |
<li><a href="/handbook/marketing/blog/community-writers/">Community Writers Program</a> Lead</li>
<li><a href="/handbook/marketing/developer-relations/technical-writing/markdown-guide/">Markdown Kramdown</a> <a href="/jobs/expert/">Expert</a></li>
<li><a href="/handbook/product/technical-writing/community-writers/">Community Writers Program</a> Lead</li>
<li><a href="/handbook/product/technical-writing/markdown-guide/">Markdown Kramdown</a> <a href="/jobs/expert/">Expert</a></li>
story: |
Marcia is passionate about computers since the early 1990s, when she first touched the
command line and somehow managed to play games on DOS. Her background in Science opened the way for technical
source/community/writers/index.html.markdown
+ 1
− 1
View file @ 3c8f7b11
@@ -8,4 +8,4 @@ suppress_header: true
 
 
The content of this page was transferred to the
[Blog Handbook - Community Writers Program](/handbook/marketing/blog/community-writers/).
[Blog Handbook - Community Writers Program](/handbook/product/technical-writing/community-writers/).
source/handbook/git-page-update/index.html.md
+ 1
− 1
View file @ 3c8f7b11
@@ -60,7 +60,7 @@ Instructions on how to update the website are in the
[readme of www-gitlab-com](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/README.md).
 
Most pages that you might want to edit are written in markdown [Kramdown](http://kramdown.gettalong.org/).
Read through our [Markdown Guide](/handbook/marketing/developer-relations/technical-writing/markdown-guide/) to understand its syntax and create new content.
Read through our [Markdown Guide](/handbook/product/technical-writing/markdown-guide/) to understand its syntax and create new content.
 
### Local Checks of Your Changes
 
source/handbook/index.html.md
+ 3
− 3
View file @ 3c8f7b11
@@ -4,7 +4,6 @@ title: Team Handbook
twitter_image: '/images/tweets/handbook-gitlab.png'
---
 
The GitLab team handbook is the central repository for how we run the company. Printed it consists of about 500 pages of text. As part of our value of being transparent the handbook is <a href="https://gitlab.com/gitlab-com/www-gitlab-com/tree/master/source/handbook">open to the world</a>, and we welcome feedback<a name="feedback"></a>. Please make a <a href="https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests">merge request</a> to suggest improvements or add clarifications.
Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues</a> to ask questions.
 
@@ -37,9 +36,8 @@ Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues<
* [UX](/handbook/ux)
* [Build](/handbook/build)
* [Marketing](/handbook/marketing)
* [Content Team](/handbook/marketing/content/)
* [Content Marketing](/handbook/marketing/content/)
* [Blog](/handbook/marketing/blog)
* [Markdown Guide](/handbook/marketing/developer-relations/technical-writing/markdown-guide/)
* [Social Marketing](/handbook/marketing/social-marketing/)
* [Social Media Guidelines](/handbook/marketing/social-media-guidelines)
* [Sales](/handbook/sales)
@@ -50,6 +48,8 @@ Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues<
* [Product](/handbook/product)
* [Making Gifs](/handbook/product/making-gifs)
* [Data analysis](/handbook/product/data-analysis)
* [Technical Writing](/handbook/product/technical-writing/)
* [Markdown Guide](/handbook/product/technical-writing/markdown-guide/)
 
<style>
.md-page h2 i.icon-color {
source/handbook/marketing/blog/community-writers/index.html.markdown
+ 1
− 111
View file @ 3c8f7b11
@@ -5,114 +5,4 @@ description: "Start today and earn up to $200 an article."
twitter_image: /images/handbook/marketing/community-writers-twitter-illustration.png
---
 
<br>
![Write for GitLab](/images/handbook/marketing/community-writers-twitter-illustration.png)
{::options parse_block_html="true" /}
<div class="alert alert-purple center">
## <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Get paid to write for GitLab <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{:.gitlab-orange .text-center #write-for-gitlab}
</div>
We want to publish you! **Earn up to $200 per article** writing for the [GitLab Blog].
Are you great at solving challenging problems or explaining complex ideas? Do you
have a specific area of expertise and want to share your knowledge? Help us expand
our range of tutorials and advice about creating, collaborating, and deploying with
Git and GitLab. You don't have to be an experienced writer, we will work with you
to revise, refine, and publish your post to share with our community.
## How It Works
1. Choose a topic
2. Start writing
3. Receive feedback
4. Get published
5. Get paid
All of GitLab's blog posts begin as an issue in the [GitLab blog post project][blog-project].
To become a community author:
- Select an issue from <https://gitlab.com/gitlab-com/blog-posts/issues> [labeled](#labels) with "[up-for-grabs]"
- Submit the first two paragraphs of an article or a link to a relevant article that you've written before.
- Leave a comment "@marcia I would like to write this post, and I accept the terms on the [Community Writers Program](#)"
If you don't see a topic that interests you, you can propose a new topic by
creating a new issue and following the last two instructions above. Once approved Marcia will leave a comment "@username, you got it!" and you can start writing!
## Get Paid
- In-depth tutorials or opinion pieces of 750+ words: **[USD 200.00]**
- Short tutorials of 500-750 words: **[USD 100.00]**
- [Top-priority][]: **USD 200.00**
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(49, 112, 143);"></i>&nbsp;
Issues labeled **TOP PRIORITY**, will be compensated at **USD 200** regardless of length.
{:.alert .alert-info .text-center #top-priority}
When your post gets published, send us an invoice. GitLab will pay you in
American Dollars (USD) from a bank account in the USA, via wired transfer
to your bank account.
## Requirements
- Good written English
- Some previous experience in writing tutorials or technical overviews
- Some background on the subject you're willing to write about
- Be familiar with GitLab
## Notes
- If you want to write about your own product (or the product you represent), and how it integrates with GitLab, we'll be happy to have you as a [Guest Writer](../#guest-posts). The Community Writers Program won't apply for these cases.
- You are encouraged to write more than one post. If you succeed on the first process, we'll invite you to write for us regularly. The process for writing more than one post is exactly the same for writing the first one. Please, pick up an issue at a time.
- Your post must be original, comprehensible, technical, and unprecedented.
## Learn More
We have some standards and guidelines that need to be respected. Please make sure you're familiar with and accept them:
- [Publishing Process for Community Writers][publishing-process]
- [Blog Style Guidelines][blog-style]
- [Writing Method]
- [Markdown Guide]
<!-- identifiers -->
[avail-posts]: https://gitlab.com/gitlab-com/blog-posts/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Community+Posts&label_name%5B%5D=up-for-grabs
[blog-project]: https://gitlab.com/gitlab-com/blog-posts
[blog-style]: /handbook/marketing/blog/#styles-guidelines
[CI/CD/CD]: /2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
[ConvDev]: /2016/09/13/gitlab-master-plan/#convdev
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[publishing-process]: /handbook/marketing/blog/#publishing-process-for-community-writers
[gitlab blog]: /blog/
[Pages group]: https://gitlab.com/groups/pages
[Writing Method]: /handbook/marketing/developer-relations/technical-writing/#writing-method
[topics-issues]: https://gitlab.com/gitlab-com/blog-posts/issues/
<!-- labels -->
[Community Posts]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=Community+Posts
[up-for-grabs]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=up-for-grabs
[USD 100.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24+100
[USD 200.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24200
[TOP-PRIORITY]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=TOP+PRIORITY
<style>
.center {
text-align: center;
display: block;
margin-right: auto;
margin-left: auto;
}
.alert-purple {
color: rgb(107,79,187);
background-color: #fff;
border-color: rgba(107,79,187,.5);
}
.alert-purple h2 {
margin-top: 15px;
}
</style>
This page have been [moved](/handbook/product/technical-writing/community-writers/).
source/handbook/marketing/blog/index.html.md
+ 15
− 15
View file @ 3c8f7b11
@@ -337,7 +337,7 @@ Read the section [Performing Reviews](#performing-reviews) for further details.
 
For our [community writers], we will follow the Scalable Writing System described below, coordinated by the [Blog Editorial Team].
 
1. Community Writer: detailed in [community writers program](https://about.gitlab.com/handbook/marketing/blog/community-writers/)
1. Community Writer: detailed in [community writers program](/handbook/product/technical-writing/community-writers/)
1. Content Marketing - analyses the proposal:
- Marcia will evaluate the writer's sample and discuss anything necessary before the author start writing
- If the issue isn't already labeled with the [compensation labels](#compensation-labels) (`$100`, `$200`, `TOP PRIORITY`), Marcia will define the compensation the post is worth and attribute the correct label.
@@ -958,11 +958,11 @@ To keep our blog posts consistent with one another, let's follow these simple gu
- [`categories`](#categories): use either `release` or `security release` for these posts.
 
- There are some important things to note when adding:
- [Videos](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#videos) => they must be wrapped by a `<figure>` tag with the class `video_container`, otherwise they will not look well on mobile phones. The `<figure>` tag is [very important for SEO](https://www.searchenginejournal.com/html5-an-essential-weapon-for-seos/62512/).
- [Images](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#images) => always add an `ALT` text, try to make the image filename meaningful => they will show up on Google searches more often and more accurately => again, important for SEO.
- Use [colorful sections](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#colorful-sections) to highlight the main points (use it wisely :)
- [Add `{:.shadow}` to images](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#shadow), specially GitLab UI screenshots
- Add the [class `{:.note}` for notes](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#note), instead of making them look like blockquotes, which are technically meant for quoting someone else's sayings.
- [Videos](/handbook/product/technical-writing/markdown-guide/#videos) => they must be wrapped by a `<figure>` tag with the class `video_container`, otherwise they will not look well on mobile phones. The `<figure>` tag is [very important for SEO](https://www.searchenginejournal.com/html5-an-essential-weapon-for-seos/62512/).
- [Images](/handbook/product/technical-writing/markdown-guide/#images) => always add an `ALT` text, try to make the image filename meaningful => they will show up on Google searches more often and more accurately => again, important for SEO.
- Use [colorful sections](/handbook/product/technical-writing/markdown-guide/#colorful-sections) to highlight the main points (use it wisely :)
- [Add `{:.shadow}` to images](/handbook/product/technical-writing/markdown-guide/#shadow), specially GitLab UI screenshots
- Add the [class `{:.note}` for notes](/handbook/product/technical-writing/markdown-guide/#note), instead of making them look like blockquotes, which are technically meant for quoting someone else's sayings.
 
<!-- Identifiers, in alphabetical order -->
 
@@ -979,7 +979,7 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[Blog post style guide]: https://gitlab.com/gitlab-com/blog-posts/blob/master/STYLEGUIDE.md
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[Community Writers]: community-writers/
[example]: /handbook/marketing/developer-relations/technical-writing/#st-subject-audience-requirements
[example]: /handbook/product/technical-writing/#st-subject-audience-requirements
[GitLab Flow]: //doc.gitlab.com/ee/workflow/gitlab_flow.html
[GitLab Workflow]: https://www.youtube.com/watch?v=enMumwvLAug "Introduction to GitLab Workflow"
[GitLab]: /
@@ -991,10 +991,10 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[public domain]: https://en.wikipedia.org/wiki/Public_domain
[Realm.io]: //realm.io
[styles guidelines]: #styles-guidelines
[tech-writing-audience]: /handbook/marketing/developer-relations/technical-writing/#st-subject-audience-requirements
[tech-writing-audience]: /handbook/product/technical-writing/#st-subject-audience-requirements
[tinypng]: //tinypng.com
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[writing-tech]: /handbook/marketing/developer-relations/technical-writing/#professional-writing-techniques
[writing-tech]: /handbook/product/technical-writing/#professional-writing-techniques
[`www-gitlab-com`]: https://gitlab.com/gitlab-com/www-gitlab-com/
 
<!-- BLOG STYLE GUIDELINES -->
@@ -1014,12 +1014,12 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[blog]: /blog/
[bundler]: http://bundler.io/
[Chicago Manual of Style]: http://www.chicagomanualofstyle.org/home.html
[code-editors]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#markdown-editors
[code-editors]: /handbook/product/technical-writing/markdown-guide/#markdown-editors
[convox-post]: /2016/06/09/continuous-delivery-with-gitlab-and-convox/
[cross-1]: /2016/08/04/moving-to-gitlab-yes-its-worth-it/
[cross-2]: /2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/
[cross-3]: /2016/08/19/applying-gitlab-labels-automatically/
[css-shadow]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#special-classes
[css-shadow]: /handbook/product/technical-writing/markdown-guide/#special-classes
[description-tag]: http://www.wordstream.com/meta-tags
[Digital Ocean]: /2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/
[documentation]: http://docs.gitlab.com/
@@ -1036,15 +1036,15 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[Koding]: /2016/07/26/koding-and-gitlab-integrated/
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Making Gifs]: /handbook/product/making-gifs
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Markdown Style Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Markdown Guide]: /handbook/product/technical-writing/markdown-guide/
[Markdown Style Guide]: /handbook/product/technical-writing/markdown-guide/
[marketing-blog]: #blog
[Mattermost]: /2015/08/18/gitlab-loves-mattermost/
[middleman]: https://middlemanapp.com/basics/install/
[MR-description]: https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/2740/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[OG]: https://developers.facebook.com/docs/sharing/webmasters#markup
[outlines]: /handbook/marketing/developer-relations/technical-writing/#3rd-plan
[outlines]: /handbook/product/technical-writing/#3rd-plan
[Pivotal Cloud Foundry]: /2015/11/03/pivotal-cloud-foundry-tile-for-gitlab-ee/
[post-iOS-CI]: /2016/03/10/setting-up-gitlab-ci-for-ios-projects/
[post-lets-encrypt]: /2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/
@@ -1068,7 +1068,7 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[width-post]: /2016/08/05/feature-highlight-set-dates-for-issues/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
[wrap text]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#wrapping-text
[wrap text]: /handbook/product/technical-writing/markdown-guide/#wrapping-text
[Yubico]: /2016/08/31/gitlab-and-yubico-security-webcast/
 
<!-- Labels -->
source/handbook/marketing/developer-relations/index.html.md
+ 1
− 2
View file @ 3c8f7b11
@@ -4,10 +4,9 @@ title: "Developer Relations"
---
# Welcome to the Developer Relations Handbook
 
The Developer Relations organization includes Developer Advocacy and Technical Writing.
The Developer Relations organization includes Developer Advocacy and Community Advocacy.
 
Developer Relations Handbooks:
 
- [Developer Advocacy](/handbook/marketing/developer-relations/developer-advocacy/)
- [Community Advocacy](/handbook/marketing/developer-relations/community-advocacy/)
- [Technical Writing](/handbook/marketing/developer-relations/technical-writing/)
source/handbook/marketing/developer-relations/technical-writing/index.html.md
+ 1
− 224
View file @ 3c8f7b11
@@ -3,227 +3,4 @@ layout: markdown_page
title: "Technical Writing"
---
 
### Welcome to the Technical Writing Handbook!
{:.no_toc}
----
## On this page
{:.no_toc}
* Will be replaced with the ToC, excluding the "On this page" header
{:toc}
----
## Technical Writing
[Technical Writers] are part of the Developer Relations Marketing Team. Their mission is to
help GitLab to:
- have all features well documented
- ensure the information regarding GitLab CE/EE/CI and its particularities are up to date
- write guides, recipes, and blog content
- assist the team with documentation and non-documentation tasks
- review every technical content published in the channels we use
[Documentation] helps the GitLab community to:
- setup and administrate their accounts
- setup and update GitLab instances
- use every tool and feature
- handle integrations, services, and tools
Docs are written technically, methodically,
programmatically, clearly, and practically.
[Blog posts][blog] have the same purpose of assisting the GitLab community,
but with a more flexible and reader-friendly language. Also,
besides the technical content, posts can be informative, tell use-case stories,
customer experience, and present a much more diverse
sort of content, since it's somehow interesting for our audience.
Whenever we write for GitLab, it's necessary to keep in mind that we are writing _on behalf_ of GitLab. We are representing the
company. Therefore, it's important to keep our personal opinions, tendencies, and point of views apart, and try to be clear, direct, concise, and professional above all. This is detailed right below, on the section [Professional Writing Techniques].
Make sure to read this through before writing for GitLab.
Also, our content is written in markdown Kramdown. Make sure to read the [Markdown Style Guide] before adventuring yourself writing for
our website [about.GitLab.com] and our [Blog], which are our "faces to the world".
On the [GitLab Blog Handbook][marketing-blog], you'll find out more about the GitLab
Blog directive, and the [Blog Style Guidelines][blog-guidelines].
## Markdown Style Guide for about.GitLab.com
Check out our [Markdown Style Guide] for the markup used throughout about.GitLab.com, including any markdown page and blog post. You'll
find useful information there, some [Kramdown] magic, and it might save you a lot of typing.
----
## Professional Writing Techniques
When writing professionally, it's important to understand some standards to follow through, for the purpose of achieving high quality work in a optimum time for conclusion.
Technical papers have the characteristic of being less personal and more formal: they're not the right place to express our opinions, nor to give advice. Accuracy matters most.
For classical scientific papers, the rules are much more restrictive and the language is absolutely formal. For blog posts, we need to use a middle term. Be clear, precise, and professional, but be empathetic and "reader-friendly". A discrete and occasional touch of humor is also welcome.
When writing non-technical blog posts, we can be less formal and more personal, depending on the subject we are writing about. In any case, though, we need to be professional. Meaning, we can be friendly and personal, but we need to focus on the point. The method suggested in this document is valid for both technical and non-technical themes, once it's related to the process of writing, not to the content itself.
Before writing on behalf of GitLab, make sure you've read through this [guide][marketing-blog].
### Technical Blog Posts
Are considered [technical][tech-writing-wiki] posts: tutorials, guides, overviews, techniques, methods, processes, and anything else which requires some sort of technical knowledge or standard procedure. For them, follow all the steps described in the [writing method](#method).
### Non-Technical Blog Posts
For non-technical post, we won't need to get into all the [steps](#method) below. Check which category matches best with the subject you'll be working on to know how to proceed.
- **Personal Experience**
- _Personal content_: user stories, user experience, opinion-based overviews and comparisons, etc.
- _Inside GitLab_
Skip the steps: [4th. Research](#th-research) and [7th. Test](#th-test).
- **Information** (If the content is not a tutorial or a guide, but it has informative purposes)
- _Feature overviews_
- _Product comparisons_
- _Case studies_
The [7th](#th-test) step can be skipped. For the [4th](#th-research) step, provide links to corroborate your information.
- **Quick Announcements**
- _Release announcements_
- _Feature highlights_
All the steps can be skipped, **except**: 1st, 6th, 8th, 9th, and 10th.
- **Other**
If your chosen subject doesn't match any previous category, read through the method, and try to use your sense to adapt it according to your case. Fell free to ask for help if needed.
### Writing Method
The following method suggests steps to take in order to create high quality written productions. This approach is recommended, but flexible. Feel free to adapt it to your needs.
#### 1st. Subject, Audience, Requirements
The first step to take if defining the subject, the audience, the knowledge level, and the requirements.
- Choose a subject you are very familiar with and comfortable to explain it in deep details.
- Create a title for your article, based on the previous step. A good title is very short, and accurate.
- Choose the audience:
- Who might have interest on this subject? Which instance of GitLab would be involved? GitLab EE, CE?
- What is the expertise level necessary to follow your steps? The user needs to be familiar with the subject, or comfortable with, or need to be an expert?
- What is required o make it work locally for the user? Specify the Operational System, any necessary software, any hardware condition.
- Add this information to a new issue on the [blog posts issue tracker][blog-tracker]
- Mind that you'll need to create a sentence to be included in the beginning of the article with this information. It can be explicit or subjective.
For example, for a tutorial for Android: _"We assume you know the process of creating an Android App, you already have projects running locally, and you are familiar with the GitLab UI"_. This would tell the reader that he needs to be an intermediate/advanced app developer, he/she needs to have every software necessary to run an Android application installed locally, and he/she has used GitLab before.
#### 2nd. Brainstorm
Think about everything that is possible for the subject you want to follow through. Write down every piece of information, every detail, every cool stuff that can be achieved, schemes, key processes, any knowledge that can be included in a text about your theme. Doesn't matter the order, if it's important or not, if makes absolute sense or not. Free your brain and let it work with no boundaries. Here the creativity and originality matters most.
#### 3rd. Plan
Perfect. Now you have a lot of ideas to organize. On this part you will filter the important things from your brainstorming notes, arrange them in some logic, and cut off what's not necessary. You'll do that by creating the _outlines_ for your article. Organize the headings in titles, subtitles, bullet points, brief descriptions, and include important [(key)words] that popped up into your head and you want to include in your article.
Keep in mind the audience you'd chosen before. Do not complicate things if you are writing for beginners, nor simplify too much if you're targeting advanced personal.
#### 4th. Research
Now that you know what you want to include in your paper, it's time to find reliable sources to support your scheme. You know the process, but you need to include sources for technical information.
For example, let's consider a post about Android Apps. If you say that you need an emulator for previewing your Android app locally, provide a link to the [official Android documentation][android-doc] where it's said that you need an emulator, and also add a link for the [emulator][android-emulator] itself.
Search for the sources you already know you'll need. Copy and paste the links with interesting information to a text document, or bookmark them, however you prefer. Gather the links in a way you can find them easily, to include them while you draft.
Mind that this step will end only when your post is published. You will need to come back to search for sources again and again, until the end.
A _reliable source_ is officially documented information, content described in books, newspaper's articles, scientific papers, etc. <!-- some ideas to make a better sentence here? -->
#### 5th. Draft
Now that you have a skeleton for your article, and some links to guide you through, you'll start to write, filling the gaps along the structure you'd planned before.
Never make a statement without providing the source for that information, unless it is your own conclusion, and you have the expertise to defend it. This posture will avoid mistrust and lost of credibility. Follow the [Writing Tips](#writing-tips) below.
It's much quicker to write with a previous plan. Go on and write everything you need. Don't try to review every sentence or to think too much before writing down. You'll have time to review afterwards.
#### 6th. Improve
After you finished, read everything again, and see if you're not repeating yourself, or if there is some unnecessary information. Cut off everything nonessential. This will have been your first review.
After your first review, try to do other things to intentionally deviate your attention from the text. Preferably, close the file and open it just in the next day, after some sleep. This will help you to clear your head, then you'll catch mistakes you wouldn't have after several hours working on the same thing.
Now, along your second review, it's time to spot typos and grammar mistakes. Check if the text sounds clear, easy to understand and if it's not boring. Make any necessary adjustments, then start the review over again.
#### 7th. Test
If you wrote a tutorial or any procedure that can be tested, test it. Go over your steps **exactly as you described them**, and check if you succeed following your own steps. Preferably test in as many conditions as possible: using different Operational Systems, distinct configurations, different versions, whatever applies to your case. If you have someone close to you that could contribute testing it for you too, better yet. After testing, go through the steps 4th to 6th again, if necessary.
#### 8th. Submit
When you're happy with your draft, submit it in a [WIP][WIP MR] (Work In Progress) merge request.
#### 9th. Review
Mind that your reviewers will probably ask for changes, make difficult questions, insist in some points. Do not be discouraged by the review. It will only help you to succeed even more, and to enhance the quality of your work.
If you don't agree with the reviewer at some point, just say it. Discuss your matter and defend your point of view, until you both agree with each other.
#### 10th. Publish
After you adjust the post according to the reviewers' requests, it will get published and everybody will be happy for you!
### Writing Tips
There is a simple list below, for things to do and to avoid when writing. It's not a exact science, though. Try to balance between what's best and what's possible, be yourself, and use your sense.
- Be original: do not repeat yourself - nor repeat other posts and documentation
- Be concise: say what you need to say. Not more, nor less
- Be attentive: do not repeat the same word, use [synonyms]
- Be smart: try to predict questions - and answer them along the text
- Be precise: do not make any statement if you don't have a reliable source or the expertise to defend it
- Be clear: everything seems to be logic for whom is writing. Not necessarily for those reading
- Be organized: in tutorials, do not jump over a step presuming the audience knows that. It breaks logic and looses engrossment
- Be consistent: try to adopt patterns to facilitate the comprehension
- Be professional: prefer "it is" over "I think"
- Be inclusive: use "we" rather then "you" or "I"
- Be creative: think _out-of-the-box_ and explore things _out-of-the-blue_
----
<!-- Identifiers, in alphabetical order -->
[about.GitLab.com]: https://about.gitlab.com/
[android-doc]: http://developer.android.com/intl/pt-br/tools/help/emulator.html
[android-emulator]: http://developer.android.com/intl/pt-br/tools/devices/emulator.html
[blog]: https://about.gitlab.com/blog
[blog-guidelines]: /handbook/marketing/blog/#styles-guidelines
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[bundler]: http://bundler.io/
[documentation]: http://docs.gitlab.com/
[git]: https://git-scm.com/
[issue-docs]: https://gitlab.com/gitlab-org/gitlab-ce/issues/
[(key)words]: http://www.wordstream.com/seo-keyword
[Kramdown]: http://kramdown.gettalong.org
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Markdown Style Guide]: markdown-guide/
[marketing-blog]: /handbook/marketing/blog/
[middleman]: https://middlemanapp.com/basics/install/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[Professional Writing Techniques]: #professional-writing-techniques
[Screenshot Tool]: https://help.ubuntu.com/lts/ubuntu-help/screen-shot-record.html
[Snipping Tool]: https://support.microsoft.com/en-us/help/13776/windows-use-snipping-tool-to-capture-screenshots
[synonyms]: http://www.thesaurus.com/
[technical aspects]: https://about.gitlab.com/handbook/marketing/product-marketing/content-marketing/#technical-aspects
[technical writers]: /jobs/technical-writer/
[tech-writing-wiki]: https://en.wikipedia.org/wiki/Technical_writing
[tinypng]: https://tinypng.com/
[unsplash]: https://unsplash.com/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
[Technical Writing](/handbook/product/technical-writing/) was transferred to the [Product](/handbook/product/) Team.
source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md
+ 1
− 2025
View file @ 3c8f7b11
@@ -4,2028 +4,4 @@ title: "Markdown Guide"
description: "Read through our Markdown Kramdown Style Guide!"
---
 
<br>
#### Welcome to the Markdown Kramdown Style Guide for [about.GitLab.com]
{:.no_toc}
----
## 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.
### Blog
For our [Blog], everything in this guide can be applied. Read through the [Blog Style Guidelines] and the
[Professional Writing Techniques] for further information.
----
## Headings
```md
## Heading h2
### Heading h3
#### Heading h4
```
{::options parse_block_html="true" /}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
## Heading h2
{:.no_toc style="margin-top:0"}
### Heading h3
{:.no_toc}
#### Heading h4
{:.no_toc}
</div>
</div>
Notes:
- We don't use `h1` headings, as they already are displayed on every page as its title, and we should not apply more than one `h1` per page.
> _When you use a top level heading, or an <h1>, you’re setting up a semantic relationship between that heading and the remainder of the content on a page, describing what it is about. If you then use a second <h1> on the same page, you’re creating some potential confusion, because someone, or a search engine might see that as the ending of the semantic relationship between the content after the first <h1> and the start of this new <h1>._ [SEO Guide]
- Always start with `h2` (`##`), and respect the order h2 &rarr; h3 &rarr; h4. Never skip the hierarchy level, such as h2 &rarr; h4.
> _The six heading elements, H1 through H6, denote section headings. Although the order and occurrence of headings is not constrained by the HTML DTD, documents **should not skip levels** (for example, from H1 to H3), as converting such documents to other representations is often problematic._ [W3C]
- Always leave a blank space between the hash `#` and the text next to it, otherwise it won't render properly.
- For keeping the text clear and the markdown consistent, [jump a line](#jump-a-line) between any heading and its subsequent paragraph.
----
## 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, which is called [wrapping text][wrap].
But, if you leave a blank line between them, they will split into two paragraphs.
### Wrapping Text
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 `<br>`.
#### 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.
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
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.
</div>
</div>
### Additional breaks
In case you need an additional break (or some extra space between lines), you can simply use the HTML break tag `<br>`,
leaving blank lines above and below it:
```html
Text A
<!-- blank line -->
<br>
<!-- blank line -->
Text B
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Text A
<br>
Text B
</div>
</div>
### 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
<!-- blank line -->
----
<!-- blank line -->
Text
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Text
----
Text
</div>
</div>
----
## Emphasis: bold and italic
To display bold or italic text, wrap it into stars or underlines:
```md
This is **bold** and this is _italic_.
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is **bold** and this is _italic_.
</div>
</div>
----
## 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.
### Inline Links
We'd rather use inline links, such as `[Text to display](link)`, as they are easier to maintain.
Use relative URLs whenever possible.
### Identifiers
When there are **repeated** links across a single page, you can opt for using identifiers.
Place the identifiers at the end of the paragraph (or the section), arranging them in alphabetical order.
```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.
[This link][] (same as above), has a second pair of empty brakets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
[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.
[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
</div>
</div>
Important notes:
{: #links-important-notes}
- {: #note-identifiers} Identifiers **are not** case sensitive. They can be single words as `[link]` or `[multiple words too]`.
- {: #note-meaningful-links} 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.
- {: #note-deadlinks-checker} Check for broken links: <http://www.deadlinkchecker.com/>
----
## 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.
**Important:** always leave a blank line between the paragraph or heading and the subsequent list!
If you don't, the list will not render.
{:.alert .alert-info}
### Ordered lists
Ordered lists are pretty easy to create. Couldn't be more intuitive:
```md
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
3. Sub item three
2. Item two
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
3. Sub item three
2. Item two
</div>
</div>
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
Paragraph:
1. Item one
1. Sub item one
1. Sub item two
1. Item two
1. Item three
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
1. Item two
1. Item three
</div>
</div>
### Unordered lists
Unordered lists are very easy to create too:
```md
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
</div>
</div>
### 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_
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
- 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_
</div>
</div>
----
## 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]
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
[![An awesome example image](/images/about-gitlab-com.png "Hello World")*My caption*][about.gitlab.com]
</div>
</div>
**Important notes:**
{:#images-important-notes}
- {: #image-shadow} Apply [shadow](#shadow) to your images!
- {: #image-requirements} All images must be placed [under `/source/images/`][source-img], in an appropriate directory. Only screenshots
and public domain images are permitted.
- {: #image-alt-text} 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.
- {: #image-filename} 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.
- {: #image-title} It's also recommendable adding an image title, as the "Hello World" exemplified above.
----
## Videos
There are two ways of displaying videos: within HTML5 `<video>` tags and within `<iframe>` tags.
### Display videos from YouTube
This method works for YouTube videos and any other embed video within an `<iframe>` tag.
1. Copy the code below and paste it into your markdown file. Leave a blank line above and below it
1. Go the video URL you want to display
1. Click on "Share", then "Embed"
1. Copy the `<iframe>` source (`src`) URL **only**, and paste it replacing the `src` below:
```html
<!-- blank line -->
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
</div>
</div>
### Display other videos
This method works for any video uploaded to somewhere retrievable from the internet from a URL, or from a relative
path like `path/to/video.mp4`.
1. Read through the [w3schools HTML5 video guide][w3-video], or the [MDN `<video>` guide][mdn-video].
1. Record or export the video in these three formats to achieve cross-browser and cross-device
compatibility: `.mp4`, `.ogg` and `.webm`.
1. Get the URL for your video
1. Choose an image to use as a poster
1. Copy the code below and paste it to your file
1. Replace the `src` URLs for your video URLs
```html
<!-- blank line -->
<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="path/to/poster_image.png">
<source src="path/to/video.mp4" type="video/mp4">
<source src="path/to/video.ogg" type="video/ogg">
<source src="path/to/video.webm" type="video/webm">
</video>
</figure>
<!-- blank line -->
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="/images/default-blog-image.png">
<source src="html5-demo.mp4" type="video/mp4">
</video>
</figure>
</div>
</div>
_**Note:** in case you don't have all formats recommended by **w3schools**, you can use just one of them,
but your video most likely won't be supported in all devices and browsers. The video above (`.mp4` only)
worked on Mozilla Firefox for OS X, Android, and Windows, and on Chrome for Android and for Windows.
But it may not work on other devices/browser, such as Chrome for OS X and iOS, or Safari.
In fact, the best option is using YouTube or Vimeo embed videos in `<iframe>` tags._
{: .note}
----
## Table of Contents (ToC)
With Kramdown, creating a Table of Contents is the easiest thing ever! The automatic ToC will include every heading in
the document, unless you don't want it to be included. You do not need to add anchors individually to every title. This is
an automated process.
```md
----
## On this page
{:.no_toc}
- TOC
{:toc}
----
```
As always, leave a blank line before and after the markup. Note that there are four dashes beginning
and closing the block, which is not required, but recommendable for keeping the same standards through about.GitLab.com.
The heading "On this page" can be adapted to your case, e.g., "In this tutorial", or "In this guide", etc. It's not required
either, but recommended.
The markup `{:.no_toc}` is used every time you don't want to include a heading into the ToC. Just add
it right below the heading, and it won't be included into the ToC. In fact `no_toc` is a
[custom class](#classes-ids-and-attributes), as described later in this guide.
The **output** ToC can be found at the very beginning of this page.
Alternatively, you can use ordered ToC too, displaying numbers at the beginning of the list. Just use the markup for
ordered lists and Kramdown will be smart enough to understand what you want:
```md
1. TOC
{:toc}
```
----
## Tables
Tables for markdown are challenging. So, we have two possible approaches: use markdown markup whenever possible,
but if you need pretty advanced table layouts, you are free to add them in HTML markup instead.
> _Markdown is not a replacement for HTML, or even close to it. ([John Gruber][daring-quote])_
{: #quote}
As explained by John Gruber, the creator of markdown, it has not been created to replace HTML,
so there are situations we can't run from using HTML. With complex tables, that's the case.
The following table has a header (first line), then markup to define the desired alignment (dashes and colons),
then the table body. You can go forward and add a separator to create subsequent table bodies.
However you prepare your table, its design will depend upon the CSS styles defined for them.
The last markup `{: .custom-class #custom-id}` **can** be used in case you want to attribute to
the `<table>` element a [custom class and/or a custom ID](#classes-ids-and-attributes).
```md
| Default aligned | Left aligned | Center aligned | Right aligned |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell | Third cell | fourth cell |
| Second line | foo | **strong** | baz |
| Third line | quux | baz | bar |
|-----------------+--------------+-----------------+----------------|
| Second body | | | |
| 2nd line | | | |
|-----------------+--------------+-----------------+----------------|
| Third body | | | Foo |
{: .custom-class #custom-id}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
| Default aligned | Left aligned | Center aligned | Right aligned |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell | Third cell | fourth cell |
| Second line | foo | **strong** | baz |
| Third line | quux | baz | bar |
|-----------------+--------------+-----------------+----------------|
| Second body | | | |
| 2nd line | | Hello World | |
|-----------------+--------------+-----------------+----------------|
| Third body | | | Foo |
{: .custom-class #custom-id}
</div>
</div>
<!-- ANOTHER CHANGE NECESSARY TO ADD TO CSS ^^ -->
Certain tools can help you to create your own complex table if you need merging lines or columns,
and more advanced layouts. This is a [Table Generator] that perhaps can help you out.
Note that the bars, spaces, and dashes were used symmetrically above just for providing a nice
view of the table markup. The symmetry is not required.
Read through the [Kramdown syntax guide][kram-tables] on tables for further information.
----
## Code blocks
There are a few options for displaying code blocks with Kramdown. Most of them use backticks ``` ` ```.
### In-line
This is an ``` `in-line` ``` code block.
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_In-line_
This is an `in-line` code block.
</div>
</div>
### Fenced
```
def hello
puts "Hello world!"
end
```
_Fenced Highlighted_
```ruby
def hello
puts "Hello world!"
end
```
or
```
def hello
puts "Hello world!"
end
```
{: .language-ruby}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Fenced_
```
def hello
puts "Hello world!"
end
```
_Fenced Highlighted_
```ruby
def hello
puts "Hello world!"
end
```
or
```
def hello
puts "Hello world!"
end
```
{: .language-ruby}
</div>
</div>
### Indented
Add 4 white spaces before every line:
def hello
puts "Hello world!"
end
_Indented Highlighted_
def hello
puts "Hello world!"
end
{: .language-ruby}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Indented_
def hello
puts "Hello world!"
end
_Indented Highlighted_
def hello
puts "Hello world!"
end
{: .language-ruby}
</div>
</div>
### Nested
Add 4 white spaces before every line. This is used when you want to display a code block
within a code block.
```
def hello
puts "Hello world!"
end
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Nested_
```
def hello
puts "Hello world!"
end
```
</div>
</div>
### In lists
Indent the text of each item in 3 white spaces. Leave blank lines between the code block and the list items,
and ident the code block in 5 white spaces:
1. Item 1
1. Item 2
```ruby
def hello
puts "Hello world!"
end
```
1. Item 3
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
1. Item 1
1. Item 2
```ruby
def hello
puts "Hello world!"
end
```
1. Item 3
</div>
</div>
----
## Blockquotes
Blockquotes are good resources to mentioning someone else's quotes, like we did [just above](#quote).
Also, can be used to emphasize a sentence or a small paragraph.
```md
> This is a blockquote.
> On multiple lines.
That may be lazy.
>
> This is the second paragraph.
----
> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
>
> * lists too
>
> and all other block-level **elements**.
>
> Even code blocks:
>
> def hello
> puts "Hello world!"
> end
> {: .language-ruby}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
> This is a blockquote.
> On multiple lines.
That may be lazy.
>
> This is the second paragraph.
----
> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
> {:.no_toc}
>
> * lists too
>
> and all other block-level **elements**.
>
> Even a code block:
>
> def hello
> puts "Hello world!"
> end
> {: .language-ruby}
</div>
</div>
----
## Notes
```md
This is a regular paragraph.
**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is a regular paragraph.
**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}
</div>
</div>
----
## Comments
_Markdown markup_
```md
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.
```
_Regular HTML markup_
<!-- This is accepted as a comment too -->
{: .language-html}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.
<!-- This is accepted as a comment too -->
</div>
</div>
----
## Anchors
Add an anchor anywhere with:
```
[](){: name="hello-world"}
Some text
```
Or simply use an ID:
```
Some text
{: #hello-world}
```
----
## Font Awesome
Yes, we can use fancy [Font Awesome] icons too.
_Regular_
```
### <i class="fa fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}
```
And you can go further, such as the following.
_Styled_
```
### <i class="fa fa-puzzle-piece fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple Puzzle Icon
{: #puzzle-purple}
### <i class="fa fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Regular_
### <i class="fa fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}
----
_Styled_
### <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple GitLab Tanuki
{: #tanuki-purple}
### <i class="fa fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}
</div>
</div>
When doing something like this to a heading, it's important give it a custom ID (e.g., `{: #puzzle}`),
otherwise the one automatically created by Kramdown will sound very awkward.
The class `fa-fw` is used when you want to display the icons as a list. They will be aligned, as well as
the text right beside them.
See live examples [on this post][ssgs-post], where the icons are used to illustrate the text.
-----
## Classes, IDs, and attributes
Defining CSS classes, and elements IDs and attributes with markdown is definitely something unusual (Kramdown magic!).
But yes, if you know how to use it, you'll love it! Check how easy it is to do that with Kramdown:
```
Paragraph
{: .class .class-1 .class-2}
Paragraph
{: #custom-id}
Paragraph
{: .class .class-1 #custom-id-1}
## Heading
{: .class .class-1 #custom-id-2}
Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}
## Heading {#hello}
List:
- {: .class} List item with custom class
- {:#id} List item with custom id
To a [link]{: #link}, in-line.
This is a [link][google-es]{:hreflang="es"} in Spanish.
[link]: https://google.com
[google-es]: https://google.es
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph
{: .class .class-1 .class-2}
Paragraph
{: #custom-id}
Paragraph
{: .class .class-1 #custom-id-1}
### Heading
{: .class .class-1 .no_toc #custom-id-2}
Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}
### Heading {#hello}
{: .no_toc}
List:
- {: .class} List item with custom class
- {:#id} List item with custom id
To a [link]{: #link}, in-line.
This is a [link][google-es]{:hreflang="es"} in Spanish.
[link]: https://google.com
[google-es]: https://google.es
</div>
</div>
### Special classes
#### Shadow
The CSS class called `shadow` should be used when your image edges are not clearly defined.
This happens when it has a white background or when it's a screenshot with text (for example,
a screenshot of our user interface). For example, this image can be mistaken as part
of the text:
![text screenshot](/images/handbook/marketing/markdown-guide-image-plain-text.png)
Now, if you apply the class `shadow` to the image, it's discretely highlighted from the text:
![text screenshot with box shadow](/images/handbook/marketing/markdown-guide-image-plain-text.png){: .shadow}
To do that, apply the class directly to the image by adding the markup `{: .shadow}` right after the image
markup:
```md
![image alternative text](/path/to/image.png){: .shadow}
```
#### Note
As [previously](#notes) explained, you can add the class `note` to paragraphs that
you don't want to call attention to:
**Note:** this is something I don't want to call attention to.
{: .note}
Markup:
```md
**Note:** this is something I don't want to call attention to.
{: .note}
```
#### Colors
Add a custom class to a heading or paragraph using the following special classes.
**GitLab Orange**
#### GitLab Orange Heading
{:.gitlab-orange .no_toc}
Markup:
```
### GitLab Orange Heading
{: .gitlab-orange}
```
**GitLab Purple**
#### GitLab Purple Heading
{:.gitlab-purple .no_toc}
Markup:
```
### GitLab Purple Heading
{: .gitlab-purple}
```
#### Text Align
By default, the text will always be aligned to the left. You have a few
options to customize it with custom classes:
- Center: `.text-center`
- Right: `.text-right`
- Justify: `.text-justify`
For demonstrations purposes, they are aligned
in an [alert box](#colorful-sections), but this can be
applied to regular paragraphs and headings.
**Align to the center**
Center-aligned
{: .alert .alert-info .text-center}
Alert box markup:
```md
Center-aligned
{: .alert .alert-info .text-center}
```
Paragraph markup:
```md
Center-aligned
{: .text-center}
```
Heading markup:
```md
### Center-aligned
{: .text-center}
```
**Align to the right**
Right-aligned
{: .alert .alert-info .text-right}
```md
Right-aligned
{: .alert .alert-info .text-right}
```
**Justify**
Justified
{: .alert .alert-info .text-justify}
```md
Justified
{: .alert .alert-info .text-justify}
```
----
## Mix HTML + Markdown Markup
Mixing HTML markup with markdown is something almost "unthinkable" to someone used to regular markdown.
And it's all over this document!
Use the following markup at the beginning of your document:
```md
{::options parse_block_html="true" /}
```
And feel free to mix everything up:
```
Something in **markdown**.
<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Something in **markdown**.
<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>
</div>
</div>
You can close the markup parser tag at any point, if you want to:
```md
{::options parse_block_html="false" /}
```
----
## Colorful sections
To add notes and warning blocks into colorful boxes,
we are making use of Bootstrap's [panel blocks] and [alert boxes].
Colorful sections are applied for very specific purposes and must not be overused.
Use panels when your description contains more than one paragraph, or a
long paragraph. For single and short paragraphs, use alert boxes instead.
When using panels, make sure to add the HTML parser markup to the beginning of your document's body:
`{::options parse_block_html="true" /}`.
{: #html-parser}
Copy paste the following code according to what you want to present to the user
and replace only the description. The available colors are:
blue (`info`), green (`success`), amber (`warning`) and red (`danger`), as follows.
### Additional Information
Use the following code for **important notes** and additional information:
```html
<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">
NOTE DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My important paragraph.
{: .alert .alert-info}
```
Blue panels render like:
<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">
INFO DESCRIPTION
</div>
</div>
And blue alert boxes render like:
My important paragraph.
{: .alert .alert-info}
If you want the text inside the alert box to be blue as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-info {
color: rgb(49,112,143) !important;
}
</style>
```
### Warnings
Use the following code for warnings, like information that may have a different
result if not used correctly:
```html
<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">
WARNING DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My warning paragraph.
{: .alert .alert-warning}
```
Amber panels render like:
<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">
WARNING DESCRIPTION
</div>
</div>
And amber alert boxes render like:
My warning paragraph.
{: .alert .alert-warning}
If you want the text inside the alert box to be amber as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-warning {
color: rgb(138,109,59) !important;
}
</style>
```
### Danger
Use the following code for crucial warnings, like commands that result to loss
of data:
```html
<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">
DANGER DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My danger paragraph.
{: .alert .alert-danger}
```
Red panels render like:
<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">
DANGER DESCRIPTION
</div>
</div>
And red alert boxes render like:
My danger paragraph.
{: .alert .alert-danger}
If you want the text inside the alert box to be red as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-danger {
color: rgb(169,68,66) !important;
}
</style>
```
### Do's and Don'ts
You can use the combination of green and red panels or alert boxes for "Do's and "Don'ts":
```html
<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">
THINGS TO DO
</div>
</div>
```
or, use an alert box:
```
TO DO.
{: .alert .alert-success}
```
Not to do:
```html
<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">
THINGS NOT TO DO
</div>
</div>
```
or, use an alert box:
```
NOT TO DO.
{: .alert .alert-danger}
```
By doing so, the green panels for "DO'S" will look like:
<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">
THINGS TO DO
</div>
</div>
or, if you chose an alert box:
TO DO.
{: .alert .alert-success}
If you want the text inside the alert box to be green as well,
we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones.
Add the following `style` tag to the end of your file.
```css
<style>
.alert-green {
color: rgb(60,118,61) !important;
}
</style>
```
And for your "DON'TS" within red panels will look like:
<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">
THINGS NOT TO DO
</div>
</div>
or, if you chose a red alert box:
NOT TO DO.
{: .alert .alert-danger}
### Custom alert panels and alert boxes
All the previously mentioned alert boxes and panels are available by
default by [Bootstrap]. If we want them in a different
color, we need [custom styles](#styles). At about.GitLab.com, we
can use the orange and the purple one, as follows.
When using panels, don't forget to add to the beginning of your file the
[HTML parser markup](#html-parser) to be able to mix HMTL + Markdown:
`{::options parse_block_html="true" /}`.
#### GitLab Orange Alert Panel
<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
Panel block markup:
```html
<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
```
#### GitLab Orange Alert Box
My text in an orange box.
{: .alert .alert-gitlab-orange}
Box block markup:
```md
My text in an orange box.
{: .alert .alert-gitlab-orange}
```
#### GitLab Purple Alert Panel
<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
Panel block markup:
```html
<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
```
#### GitLab Purple Alert Box
My text in an purple box.
{: .alert .alert-gitlab-purple}
Box block markup:
```md
My text in an purple box.
{: .alert .alert-gitlab-purple}
```
### GitLab Webcast Alert Box
To be used in a CTA for webcast announcement in blog posts.
You can use it for other purposes as well. Use it together with the [HMTL parser](#html-parser):
<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}
[webcast-link]: #
```md
{::options parse_block_html="true" /}
<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}
```
----
## Styles
Yes, guess what?
This:
```css
<style>
.purple {
color:inherit;
}
.purple:hover {
color:rgb(107,79,187);
}
</style>
```
<style>
.purple {
color:inherit;
}
.purple:hover {
color:rgb(107,79,187);
}
</style>
Plus:
```
Hey! Hover the cursor over me and guess what?! :)
{: .purple}
```
Equals to:
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Hey! Hover the cursor over me and guess what?! :)
{: .purple}
</div>
</div>
And yes, the `<style>` tag is _in_ this very markdown file. Believe it or not!
----
## Embed documents
It's easy to embed Google Docs, Sheets, Slides, and pretty much everything that
provides an iframe to use with. The only thing you need to do is use the
following code inside your markdown file and replace the iframe from the document
you want to embed:
```html
<figure class="video_container">
<iframe IFRAME CONTENT></iframe>
</figure>
```
### Google products
For Google products, with your document opened, click **File** -> **Publish to the web**.
For example here's how Google sheets will look like:
![Google Sheets - File - Publish to the web](/images/markdown-guide/file-publish-to-the-web.png)
Choose **Embed**, check your settings, click on **Publish** and copy the `<iframe>`.
Then go to your markdown file and wrap the iframe into a `<figure>` tag with the
responsive `video_container` class, as shown [in the beginning](#embed-documents).
#### Google Sheets
Let's exemplify with this [simple spreadsheet]. Follow the info [above](#google-products) to find the iframe:
![Google Sheets - Embed iframe](/images/markdown-guide/embed-google-sheet.png)
Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the `<iframe>` with your own:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
</figure>
```
#### Output:
{: .no_toc}
<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
</figure>
<br>
#### Google Slides
Let's exemplify with this [GitLab deck template]. Follow the steps [above](#embed-documents) to find the iframe:
![Google Slides - Embed iframe](/images/markdown-guide/embed-google-slides.png)
Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the `<iframe>` with your own:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/embed?start=false&loop=false&delayms=3000" frameborder="0" width="1280" height="749" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>
```
#### Output:
{: .no_toc}
<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/embed?start=false&loop=false&delayms=3000" frameborder="0" width="1280" height="749" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>
<br>
#### Google Docs
Embedding Google Docs is not a recommended practice. Prefer converting your document content
to markdown instead. If you need to embed it anyway, follow the same instructions and the same logic as
we presented for Google Sheets and Slides, wrapping the `<iframe>` with a `<figure>` tag:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
</figure>
```
### SlideShare
To embed from SlideShare, go to the document you want to embed and hit the **Share**
button located below the slides. Copy the code under **Embed** and place it
inside the `figure` tag.
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(138, 109, 59)
;"></i> Be careful to only include the iframe content and strip anything else.
SlideShare will also add some other information in the embed code which you
will have to remove, otherwise the markdown page will be broken.
{: .alert .alert-warning}
For example, let's say we wanted to include the slides from [Ivan's talk on
GitLab Pages][slideshare-ivan]. Copying the embed code and stripping everything
else except from the iframe, would result in this:
```html
<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>
```
<i class="fa fa-info-circle" aria-hidden="true" style="color: rgb(49, 112, 143)
;"></i> You can safely omit the `<figure>` tag since SlideShare's widget is
already responsive, but we are showing this that way in order to be consistent
with the rest of the handbook.
{: .alert .alert-info}
#### Output:
{: .no_toc}
<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>
----
## Embed Tweets
To add tweets to markdown, copy both `<blockquote>` and `<script>` tags
from the twitter post and paste it into your file. To make it look much
nicer, wrap the script into a `div.center` (created for this specific purpose).
**Important:** if you used the [HTML parser](#mix-html--markdown-markup) in your
post or page, you'll need to set it to `false` before the `div`.
{:.alert .alert-info}
{::options parse_block_html="false" /}
<div class="center">
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
<br>
Markup:
```md
{::options parse_block_html="false" /}
<div class="center">
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
```
For more than one Tweet, copy and paste all the code blocks from Twitter into one `div.center`:
```md
{::options parse_block_html="false" /}
<div class="center">
<!-- first tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
<!-- second tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
```
----
## Markdown Editors
Please use one of the following code editors to write in markdown, or another **code editor** of
your preference.
It is **not** recommend writing your document in a regular text editor, then copy-pasting to markdown,
as it most likely will bring some characters with a different encoding (non UTF-8), which will cause the
markdown to not render correctly.
In case you don't have a choice and need to import a text already written in a text editor, paste it
to your markdown file using **command+shift+V** on a Mac, or **control+shift+V** on Windows or Linux.
You might minimize the cause of trouble by pasting without format. But yet, is not guaranteed it
is going to work, so double check your HTML output.
_Regular Code Editors_
- [Sublime Text 3][sublime]
- [Atom]
_Markdown editors (type and preview simultaneously)_
- Markdown editors for Mac: [Mou], [iA Writer]
- In-browser markdown editor: [StackEdit]
If you're not used to writing markdown, those editors can be helpful. Check a screenshot below of a
file being edited on Mou. On your left, there's the markdown markup you're writing, and on your right,
a preview of the output. The preview won't be exactly as the final result, but it's a very good
approximation, which gives you a good idea on what you're doing while you type.
![Mou for Mac - screenshot of markdown doc write and preview][mou-screenshot]
[StackEdit] is awesome too, you can work on a markdown file even if you're alway from your computer,
or out of resources. It works from every major browser and saves automatically your work to Google Drive.
----
## Complementary Notes
{: #tips--tricks}
- Words must be separated by one single space only. Do not leave more blank spaces than the necessary,
they can render differently than the expected and can cause other issues.
- Do not leave blank spaces at the end of sentences.
- {:#jump-a-line} Always leave a blank line between markups, except between list items. Example:
---- (markup for horizontal line)
<!-- blank line -->
Paragraph.
<!-- blank line -->
Do not leave blank lines within list items:
<!-- blank line -->
- Item 1
- Item 2
- Item 3
{: .language-html}
- As explained [above](#headings), do **not** jump headings. Always do h1 &rarr; h2 &rarr; h3 &rarr; h4. Never h2 &rarr; h4.
- Prefer short titles and headings. Do not punctuate them (unless they require a question mark or an exclamation).
- Try not to punctuate list items, but if you do, be consistent and do that through all the list.
- If you have to mention a non-clickable URL, prefer using backticks: `http://an-example.com`.
- To add fancy emojis to your file, click `control+cmd+space` on your Mac and check the ⭐️ **magic**! ⭐️ Do not overuse them, please!
- If you are confused about any markup that you've found in this file, you can check its [`raw` file] for reference,
where you'll be able to see exactly how everything was written to produce the results you are seeing on this page.
## More
{: .no_toc}
Anything else you know of and is not described here? Any new magic? Any trick? Please contribute!
<!-- Identifiers, in alphabetical order -->
[`raw` file]: https://gitlab.com/gitlab-com/www-gitlab-com/raw/master/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md
[about.gitlab.com]: https://about.gitlab.com/
[alert boxes]: https://getbootstrap.com/components/#alerts
[atom]: https://atom.io/
[blog]: /blog/
[Blog Style Guidelines]: /handbook/marketing/blog/#styles-guidelines
[bootstrap]: http://getbootstrap.com/components/#alerts
[daring-quote]: http://daringfireball.net/projects/markdown/syntax#html
[font awesome]: http://fontawesome.io/icons/
[GitLab deck template]: https://docs.google.com/a/gitlab.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/edit?usp=sharing
[gitlab-markdown]: https://gitlab.com/help/markdown/markdown
[handbook-writing]: https://about.gitlab.com/handbook/communication/#writing-style-guidelines
[iA Writer]: https://ia.net/writer/
[img-seo]: http://www.practicalecommerce.com/articles/77645-6-SEO-Myths-about-Alt-Tags
[kram-tables]: http://kramdown.gettalong.org/syntax.html#tables
[kramdown]: http://kramdown.gettalong.org/
[Lightweight markup languages]: https://en.wikipedia.org/wiki/Lightweight_markup_language
[Markup language]: https://en.wikipedia.org/wiki/Markup_language
[mdn-video]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
[middleman]: https://middlemanapp.com/
[mou-screenshot]: /images/markdown-guide/mou-screenshot-preview.png "Mou for Mac - Markdown Preview"
[mou]: http://25.io/mou/
[panel blocks]: https://getbootstrap.com/components/#panels-alternatives
[Professional Writing Techniques]: /handbook/marketing/developer-relations/technical-writing/#professional-writing-techniques
[Redcarpet]: http://git.io/ld_NVQ
[SEO Guide]: http://www.seobythesea.com/2012/01/heading-elements-and-the-folly-of-seo-expert-ranking-lists/
[simple spreadsheet]: https://docs.google.com/a/gitlab.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/edit?usp=sharing
[slideshare-ivan]: http://www.slideshare.net/creatop/how-to-use-any-static-site-generator-with-gitlab-pages
[source-img]: https://gitlab.com/gitlab-com/www-gitlab-com/tree/master/source/images
[ssg]: https://www.staticgen.com/
[ssgs-post-raw]: https://gitlab.com/gitlab-com/www-gitlab-com/raw/master/source/posts/2016-06-10-ssg-overview-gitlab-pages-part-2.html.md
[ssgs-post]: https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/
[stackedit]: https://stackedit.io/
[sublime]: https://www.sublimetext.com/3
[table generator]: http://www.tablesgenerator.com/html_tables
[visually-impaired]: https://gitlab.com/gitlab-org/gitlab-ce/issues/12797
[w3-video]: http://www.w3schools.com/tags/tag_video.asp
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com
[w3c]: https://www.w3.org/MarkUp/html-spec/html-spec_5.html#SEC5.4
[wrap]: /2016/10/11/wrapping-text/#do-wrap-it
This page has been [moved](/handbook/product/technical-writing/markdown-guide/).
source/handbook/marketing/index.html.md
+ 5
− 26
View file @ 3c8f7b11
@@ -30,14 +30,12 @@ The GitLab Marketing team includes four functional groups: Demand Generation, De
- [Field Marketing]
- [Marketing Operations]
- [Online Marketing]
- [Content Marketing]
- [Design]
- [Developer Relations]
- [Developer Advocacy]
- [Community Advocacy]
- [Technical Writing]
- [Markdown Guide]
- [Product Marketing]
- [Content Team]
- [Partner Marketing]
- [Social Marketing]
- [Social Media Guidelines]
@@ -301,7 +299,7 @@ Design focuses on creating the visual brand for GitLab. Design supports product
<div class="modal-body">
<!-- EDIT FROM HERE ON LIKE NORMAL MARKDOWN -->
 
Developer Relations includes the technical writing, developer advocacy, and community advocacy functions. The team is focused on answering the following questions:
Developer Relations includes developer advocacy, and community advocacy functions. The team is focused on answering the following questions:
 
- What are scalable developer education tools?
- How do we turn in person feedback at events into actionable product requests?
@@ -335,19 +333,6 @@ What is Comm. Adv. (to be included).
[<i class="fa fa-gitlab" aria-hidden="true"></i> Matija][cmattrex]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Connor][connorshea]{:.btn .btn-orange}
 
### Technical Writing
{: .no_toc}
> _Technical writing is sometimes defined as simplifying the complex. In a concise and deceptively simple definition, it is a whole range of skills and characteristics that address nearly every field of human endeavor at some level._ ([techwhirl.com])
At GitLab, tech writers are the folks who take care of writing and maintaining technical content clear, concise, consistent, professional, and up-to-date.
[Job Description](/jobs/technical-writer/){:.btn .btn-purple-inv}
[Handbook][Technical Writing]{:.btn .btn-purple}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Axil][axil]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Marcia][marcia]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Sean][sean]{:.btn .btn-orange}
<!-- DON'T EDIT THIS PART BELOW UNLESS YOU KNOW WHAT YOU'RE DOING :) -->
</div>
<div class="modal-footer">
@@ -751,35 +736,31 @@ We use our chat internally as a communication tool. The marketing channels are a
<!-- IDENTIFIERS -->
 
[cmo]: https://about.gitlab.com/jobs/chief-marketing-officer/
[create a ToC]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#table-of-contents-toc
[Markdown Style Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[techwhirl.com]: http://techwhirl.com/what-is-technical-writing/
[create a ToC]: /handbook/product/technical-writing/markdown-guide/#table-of-contents-toc
[Markdown Style Guide]: /handbook/product/technical-writing/markdown-guide/
 
<!-- HANDBOOKS -->
 
[Blog]: /handbook/marketing/blog/
[Business Development]: /handbook/marketing/demand-generation/business-development/
[Content Team]: /handbook/marketing/content/
[Content Marketing]: /handbook/marketing/content/
[Demand Generation]: /handbook/marketing/demand-generation
[Developer Advocacy]: /handbook/marketing/developer-relations/developer-advocacy/
[Community Advocacy]: /handbook/marketing/developer-relations/community-advocacy/
[Developer Relations]: /handbook/marketing/developer-relations
[Design]: /handbook/marketing/design/
[Field Marketing]: /handbook/marketing/demand-generation/field-marketing/
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Marketing Operations]: /handbook/marketing/demand-generation/marketing-operations/
[Online Marketing]: /handbook/marketing/demand-generation/online-marketing/
[Partner Marketing]: /handbook/marketing/product-marketing/partner-marketing/
[Product Marketing]: /handbook/marketing/product-marketing
[Social Marketing]: social-marketing/
[Social Media Guidelines]: /handbook/marketing/social-media-guidelines/
[Technical Writing]: /handbook/marketing/developer-relations/technical-writing/
 
<!-- Marketing Team: GitLab.com Handle -->
 
[amanda]: https://gitlab.com/u/afolson
[amara]: https://gitlab.com/u/amara
[axil]: https://gitlab.com/u/axil
[chet]: https://gitlab.com/u/chetbackman
[cmattrex]: https://gitlab.com/u/cmattrex
[connorshea]: https://gitlab.com/u/connorshea
@@ -787,10 +768,8 @@ We use our chat internally as a communication tool. The marketing channels are a
[erica]: https://gitlab.com/u/lindberg
[jennifer]: https://gitlab.com/u/jjcordz
[luke]: https://gitlab.com/u/lukebabb
[marcia]: https://gitlab.com/u/marcia
[mitchell]: https://gitlab.com/u/mitchellwright
[ryan]: https://gitlab.com/u/rycap
[sean]: https://gitlab.com/u/SeanPackham
 
<!-- EXTRA STYLES APPLIED FOR THIS PAGE ONLY -->
 
source/handbook/people-operations/functional-group-updates/index.html.md
+ 1
− 1
View file @ 3c8f7b11
@@ -87,7 +87,7 @@ Questions? Leave a comment below or tweet [@GitLab](https://twitter.com/gitlab)!
 
#### Important Notes
 
- Make sure to use correct format for [embedding videos from YouTube](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#display-videos-from-youtube) into the blogpost. Replace the video URL only
- Make sure to use correct format for [embedding videos from YouTube](/handbook/product/technical-writing/markdown-guide/#display-videos-from-youtube) into the blogpost. Replace the video URL only
- Edit the video to start when the meeting actually starts:
- On YouTube, click **Edit** > **Enhancements**
- Click **trim**, then play until the part you want to split, and click **split**
source/handbook/product/technical-writing/community-writers/index.html.md 0 → 100644
+ 118
− 0
View file @ 3c8f7b11
---
layout: markdown_page
title: "Community Writers Program"
description: "Start today and earn up to $200 an article."
twitter_image: /images/handbook/marketing/community-writers-twitter-illustration.png
---
<br>
![Write for GitLab](/images/handbook/marketing/community-writers-twitter-illustration.png)
{::options parse_block_html="true" /}
<div class="alert alert-purple center">
## <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Get paid to write for GitLab <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{:.gitlab-orange .text-center #write-for-gitlab}
</div>
We want to publish you! **Earn up to $200 per article** writing for the [GitLab Blog].
Are you great at solving challenging problems or explaining complex ideas? Do you
have a specific area of expertise and want to share your knowledge? Help us expand
our range of tutorials and advice about creating, collaborating, and deploying with
Git and GitLab. You don't have to be an experienced writer, we will work with you
to revise, refine, and publish your post to share with our community.
## How It Works
1. Choose a topic
2. Start writing
3. Receive feedback
4. Get published
5. Get paid
All of GitLab's blog posts begin as an issue in the [GitLab blog post project][blog-project].
To become a community author:
- Select an issue from <https://gitlab.com/gitlab-com/blog-posts/issues> [labeled](#labels) with "[up-for-grabs]"
- Submit the first two paragraphs of an article or a link to a relevant article that you've written before.
- Leave a comment "@marcia I would like to write this post, and I accept the terms on the [Community Writers Program](#)"
If you don't see a topic that interests you, you can propose a new topic by
creating a new issue and following the last two instructions above. Once approved Marcia will leave a comment "@username, you got it!" and you can start writing!
## Get Paid
- In-depth tutorials or opinion pieces of 750+ words: **[USD 200.00]**
- Short tutorials of 500-750 words: **[USD 100.00]**
- [Top-priority][]: **USD 200.00**
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(49, 112, 143);"></i>&nbsp;
Issues labeled **TOP PRIORITY**, will be compensated at **USD 200** regardless of length.
{:.alert .alert-info .text-center #top-priority}
When your post gets published, send us an invoice. GitLab will pay you in
American Dollars (USD) from a bank account in the USA, via wired transfer
to your bank account.
## Requirements
- Good written English
- Some previous experience in writing tutorials or technical overviews
- Some background on the subject you're willing to write about
- Be familiar with GitLab
## Notes
- If you want to write about your own product (or the product you represent), and how it integrates with GitLab, we'll be happy to have you as a [Guest Writer](../#guest-posts). The Community Writers Program won't apply for these cases.
- You are encouraged to write more than one post. If you succeed on the first process, we'll invite you to write for us regularly. The process for writing more than one post is exactly the same for writing the first one. Please, pick up an issue at a time.
- Your post must be original, comprehensible, technical, and unprecedented.
## Learn More
We have some standards and guidelines that need to be respected. Please make sure you're familiar with and accept them:
- [Publishing Process for Community Writers][publishing-process]
- [Blog Style Guidelines][blog-style]
- [Writing Method]
- [Markdown Guide]
<!-- identifiers -->
[avail-posts]: https://gitlab.com/gitlab-com/blog-posts/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Community+Posts&label_name%5B%5D=up-for-grabs
[blog-project]: https://gitlab.com/gitlab-com/blog-posts
[blog-style]: /handbook/marketing/blog/#styles-guidelines
[CI/CD/CD]: /2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
[ConvDev]: /2016/09/13/gitlab-master-plan/#convdev
[Markdown Guide]: /handbook/product/technical-writing/markdown-guide/
[publishing-process]: /handbook/marketing/blog/#publishing-process-for-community-writers
[gitlab blog]: /blog/
[Pages group]: https://gitlab.com/groups/pages
[Writing Method]: /handbook/product/technical-writing/#writing-method
[topics-issues]: https://gitlab.com/gitlab-com/blog-posts/issues/
<!-- labels -->
[Community Posts]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=Community+Posts
[up-for-grabs]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=up-for-grabs
[USD 100.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24+100
[USD 200.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24200
[TOP-PRIORITY]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=TOP+PRIORITY
<style>
.center {
text-align: center;
display: block;
margin-right: auto;
margin-left: auto;
}
.alert-purple {
color: rgb(107,79,187);
background-color: #fff;
border-color: rgba(107,79,187,.5);
}
.alert-purple h2 {
margin-top: 15px;
}
</style>
source/handbook/product/technical-writing/index.html.md 0 → 100644
+ 233
− 0
View file @ 3c8f7b11
---
layout: markdown_page
title: "Technical Writing"
---
### Welcome to the Technical Writing Handbook!
{:.no_toc}
----
## On this page
{:.no_toc}
* Will be replaced with the ToC, excluding the "On this page" header
{:toc}
----
## Technical Writing
> _Technical writing is sometimes defined as simplifying the complex. In a concise and deceptively simple definition, it is a whole range of skills and characteristics that address nearly every field of human endeavor at some level._ ([techwhirl.com](http://techwhirl.com/what-is-technical-writing/))
At GitLab, tech writers are the folks who take care of writing and maintaining technical content clear, concise, consistent, professional, and up-to-date.
[Technical Writers] are part of the Product Team. Their mission is to
help GitLab to:
- have all features well documented
- ensure the information regarding GitLab CE/EE/CI and its particularities are up to date
- write guides, recipes, and blog content
- assist the team with documentation and non-documentation tasks
- review every technical content published in the channels we use
[Documentation] helps the GitLab community to:
- setup and administrate their accounts
- setup and update GitLab instances
- use every tool and feature
- handle integrations, services, and tools
Docs are written technically, methodically,
programmatically, clearly, and practically.
[Blog posts][blog] have the same purpose of assisting the GitLab community,
but with a more flexible and reader-friendly language. Also,
besides the technical content, posts can be informative, tell use-case stories,
customer experience, and present a much more diverse
sort of content, since it's somehow interesting for our audience.
Whenever we write for GitLab, it's necessary to keep in mind that we are writing _on behalf_ of GitLab. We are representing the
company. Therefore, it's important to keep our personal opinions, tendencies, and point of views apart, and try to be clear, direct, concise, and professional above all. This is detailed right below, on the section [Professional Writing Techniques].
Make sure to read this through before writing for GitLab.
Also, our content is written in markdown Kramdown. Make sure to read the [Markdown Style Guide] before adventuring yourself writing for
our website [about.GitLab.com] and our [Blog], which are our "faces to the world".
On the [GitLab Blog Handbook][marketing-blog], you'll find out more about the GitLab
Blog directive, and the [Blog Style Guidelines][blog-guidelines].
## Markdown Style Guide for about.GitLab.com
Check out our [Markdown Style Guide] for the markup used throughout about.GitLab.com, including any markdown page and blog post. You'll
find useful information there, some [Kramdown] magic, and it might save you a lot of typing.
----
## Professional Writing Techniques
When writing professionally, it's important to understand some standards to follow through, for the purpose of achieving high quality work in a optimum time for conclusion.
Technical papers have the characteristic of being less personal and more formal: they're not the right place to express our opinions, nor to give advice. Accuracy matters most.
For classical scientific papers, the rules are much more restrictive and the language is absolutely formal. For blog posts, we need to use a middle term. Be clear, precise, and professional, but be empathetic and "reader-friendly". A discrete and occasional touch of humor is also welcome.
When writing non-technical blog posts, we can be less formal and more personal, depending on the subject we are writing about. In any case, though, we need to be professional. Meaning, we can be friendly and personal, but we need to focus on the point. The method suggested in this document is valid for both technical and non-technical themes, once it's related to the process of writing, not to the content itself.
Before writing on behalf of GitLab, make sure you've read through this [guide][marketing-blog].
### Technical Blog Posts
Are considered [technical][tech-writing-wiki] posts: tutorials, guides, overviews, techniques, methods, processes, and anything else which requires some sort of technical knowledge or standard procedure. For them, follow all the steps described in the [writing method](#method).
### Non-Technical Blog Posts
For non-technical post, we won't need to get into all the [steps](#method) below. Check which category matches best with the subject you'll be working on to know how to proceed.
- **Personal Experience**
- _Personal content_: user stories, user experience, opinion-based overviews and comparisons, etc.
- _Inside GitLab_
Skip the steps: [4th. Research](#th-research) and [7th. Test](#th-test).
- **Information** (If the content is not a tutorial or a guide, but it has informative purposes)
- _Feature overviews_
- _Product comparisons_
- _Case studies_
The [7th](#th-test) step can be skipped. For the [4th](#th-research) step, provide links to corroborate your information.
- **Quick Announcements**
- _Release announcements_
- _Feature highlights_
All the steps can be skipped, **except**: 1st, 6th, 8th, 9th, and 10th.
- **Other**
If your chosen subject doesn't match any previous category, read through the method, and try to use your sense to adapt it according to your case. Fell free to ask for help if needed.
### Writing Method
The following method suggests steps to take in order to create high quality written productions. This approach is recommended, but flexible. Feel free to adapt it to your needs.
#### 1st. Subject, Audience, Requirements
The first step to take if defining the subject, the audience, the knowledge level, and the requirements.
- Choose a subject you are very familiar with and comfortable to explain it in deep details.
- Create a title for your article, based on the previous step. A good title is very short, and accurate.
- Choose the audience:
- Who might have interest on this subject? Which instance of GitLab would be involved? GitLab EE, CE?
- What is the expertise level necessary to follow your steps? The user needs to be familiar with the subject, or comfortable with, or need to be an expert?
- What is required o make it work locally for the user? Specify the Operational System, any necessary software, any hardware condition.
- Add this information to a new issue on the [blog posts issue tracker][blog-tracker]
- Mind that you'll need to create a sentence to be included in the beginning of the article with this information. It can be explicit or subjective.
For example, for a tutorial for Android: _"We assume you know the process of creating an Android App, you already have projects running locally, and you are familiar with the GitLab UI"_. This would tell the reader that he needs to be an intermediate/advanced app developer, he/she needs to have every software necessary to run an Android application installed locally, and he/she has used GitLab before.
#### 2nd. Brainstorm
Think about everything that is possible for the subject you want to follow through. Write down every piece of information, every detail, every cool stuff that can be achieved, schemes, key processes, any knowledge that can be included in a text about your theme. Doesn't matter the order, if it's important or not, if makes absolute sense or not. Free your brain and let it work with no boundaries. Here the creativity and originality matters most.
#### 3rd. Plan
Perfect. Now you have a lot of ideas to organize. On this part you will filter the important things from your brainstorming notes, arrange them in some logic, and cut off what's not necessary. You'll do that by creating the _outlines_ for your article. Organize the headings in titles, subtitles, bullet points, brief descriptions, and include important [(key)words] that popped up into your head and you want to include in your article.
Keep in mind the audience you'd chosen before. Do not complicate things if you are writing for beginners, nor simplify too much if you're targeting advanced personal.
#### 4th. Research
Now that you know what you want to include in your paper, it's time to find reliable sources to support your scheme. You know the process, but you need to include sources for technical information.
For example, let's consider a post about Android Apps. If you say that you need an emulator for previewing your Android app locally, provide a link to the [official Android documentation][android-doc] where it's said that you need an emulator, and also add a link for the [emulator][android-emulator] itself.
Search for the sources you already know you'll need. Copy and paste the links with interesting information to a text document, or bookmark them, however you prefer. Gather the links in a way you can find them easily, to include them while you draft.
Mind that this step will end only when your post is published. You will need to come back to search for sources again and again, until the end.
A _reliable source_ is officially documented information, content described in books, newspaper's articles, scientific papers, etc. <!-- some ideas to make a better sentence here? -->
#### 5th. Draft
Now that you have a skeleton for your article, and some links to guide you through, you'll start to write, filling the gaps along the structure you'd planned before.
Never make a statement without providing the source for that information, unless it is your own conclusion, and you have the expertise to defend it. This posture will avoid mistrust and lost of credibility. Follow the [Writing Tips](#writing-tips) below.
It's much quicker to write with a previous plan. Go on and write everything you need. Don't try to review every sentence or to think too much before writing down. You'll have time to review afterwards.
#### 6th. Improve
After you finished, read everything again, and see if you're not repeating yourself, or if there is some unnecessary information. Cut off everything nonessential. This will have been your first review.
After your first review, try to do other things to intentionally deviate your attention from the text. Preferably, close the file and open it just in the next day, after some sleep. This will help you to clear your head, then you'll catch mistakes you wouldn't have after several hours working on the same thing.
Now, along your second review, it's time to spot typos and grammar mistakes. Check if the text sounds clear, easy to understand and if it's not boring. Make any necessary adjustments, then start the review over again.
#### 7th. Test
If you wrote a tutorial or any procedure that can be tested, test it. Go over your steps **exactly as you described them**, and check if you succeed following your own steps. Preferably test in as many conditions as possible: using different Operational Systems, distinct configurations, different versions, whatever applies to your case. If you have someone close to you that could contribute testing it for you too, better yet. After testing, go through the steps 4th to 6th again, if necessary.
#### 8th. Submit
When you're happy with your draft, submit it in a [WIP][WIP MR] (Work In Progress) merge request.
#### 9th. Review
Mind that your reviewers will probably ask for changes, make difficult questions, insist in some points. Do not be discouraged by the review. It will only help you to succeed even more, and to enhance the quality of your work.
If you don't agree with the reviewer at some point, just say it. Discuss your matter and defend your point of view, until you both agree with each other.
#### 10th. Publish
After you adjust the post according to the reviewers' requests, it will get published and everybody will be happy for you!
### Writing Tips
There is a simple list below, for things to do and to avoid when writing. It's not a exact science, though. Try to balance between what's best and what's possible, be yourself, and use your sense.
- Be original: do not repeat yourself - nor repeat other posts and documentation
- Be concise: say what you need to say. Not more, nor less
- Be attentive: do not repeat the same word, use [synonyms]
- Be smart: try to predict questions - and answer them along the text
- Be precise: do not make any statement if you don't have a reliable source or the expertise to defend it
- Be clear: everything seems to be logic for whom is writing. Not necessarily for those reading
- Be organized: in tutorials, do not jump over a step presuming the audience knows that. It breaks logic and looses engrossment
- Be consistent: try to adopt patterns to facilitate the comprehension
- Be professional: prefer "it is" over "I think"
- Be inclusive: use "we" rather then "you" or "I"
- Be creative: think _out-of-the-box_ and explore things _out-of-the-blue_
----
<!-- Identifiers, in alphabetical order -->
[about.GitLab.com]: https://about.gitlab.com/
[android-doc]: http://developer.android.com/intl/pt-br/tools/help/emulator.html
[android-emulator]: http://developer.android.com/intl/pt-br/tools/devices/emulator.html
[blog]: https://about.gitlab.com/blog
[blog-guidelines]: /handbook/marketing/blog/#styles-guidelines
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[bundler]: http://bundler.io/
[documentation]: http://docs.gitlab.com/
[git]: https://git-scm.com/
[issue-docs]: https://gitlab.com/gitlab-org/gitlab-ce/issues/
[(key)words]: http://www.wordstream.com/seo-keyword
[Kramdown]: http://kramdown.gettalong.org
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Markdown Style Guide]: markdown-guide/
[marketing-blog]: /handbook/marketing/blog/
[middleman]: https://middlemanapp.com/basics/install/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[Professional Writing Techniques]: #professional-writing-techniques
[Screenshot Tool]: https://help.ubuntu.com/lts/ubuntu-help/screen-shot-record.html
[Snipping Tool]: https://support.microsoft.com/en-us/help/13776/windows-use-snipping-tool-to-capture-screenshots
[synonyms]: http://www.thesaurus.com/
[technical aspects]: https://about.gitlab.com/handbook/marketing/product-marketing/content-marketing/#technical-aspects
[technical writers]: /jobs/technical-writer/
[tech-writing-wiki]: https://en.wikipedia.org/wiki/Technical_writing
[tinypng]: https://tinypng.com/
[unsplash]: https://unsplash.com/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
source/handbook/product/technical-writing/markdown-guide/html5-demo.mp4 0 → 100644
+ 0
− 0
View file @ 3c8f7b11
File added
source/handbook/product/technical-writing/markdown-guide/index.html.md 0 → 100644
+ 2034
− 0
View file @ 3c8f7b11
---
layout: markdown_page
title: "Markdown Guide"
description: "Read through our Markdown Kramdown Style Guide!"
---
<br>
#### Welcome to the Markdown Kramdown Style Guide for [about.GitLab.com]
{:.no_toc}
----
## 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.
**Note:** this document in maintained by the [Technical Writing](../) Team.
{:.note}
### Blog
For our [Blog], everything in this guide can be applied. Read through the [Blog Style Guidelines] and the
[Professional Writing Techniques] for further information.
----
## Headings
```md
## Heading h2
### Heading h3
#### Heading h4
```
{::options parse_block_html="true" /}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
## Heading h2
{:.no_toc style="margin-top:0"}
### Heading h3
{:.no_toc}
#### Heading h4
{:.no_toc}
</div>
</div>
Notes:
- We don't use `h1` headings, as they already are displayed on every page as its title, and we should not apply more than one `h1` per page.
> _When you use a top level heading, or an <h1>, you’re setting up a semantic relationship between that heading and the remainder of the content on a page, describing what it is about. If you then use a second <h1> on the same page, you’re creating some potential confusion, because someone, or a search engine might see that as the ending of the semantic relationship between the content after the first <h1> and the start of this new <h1>._ [SEO Guide]
- Always start with `h2` (`##`), and respect the order h2 &rarr; h3 &rarr; h4. Never skip the hierarchy level, such as h2 &rarr; h4.
> _The six heading elements, H1 through H6, denote section headings. Although the order and occurrence of headings is not constrained by the HTML DTD, documents **should not skip levels** (for example, from H1 to H3), as converting such documents to other representations is often problematic._ [W3C]
- Always leave a blank space between the hash `#` and the text next to it, otherwise it won't render properly.
- For keeping the text clear and the markdown consistent, [jump a line](#jump-a-line) between any heading and its subsequent paragraph.
----
## 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, which is called [wrapping text][wrap].
But, if you leave a blank line between them, they will split into two paragraphs.
### Wrapping Text
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 `<br>`.
#### 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.
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
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.
</div>
</div>
### Additional breaks
In case you need an additional break (or some extra space between lines), you can simply use the HTML break tag `<br>`,
leaving blank lines above and below it:
```html
Text A
<!-- blank line -->
<br>
<!-- blank line -->
Text B
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Text A
<br>
Text B
</div>
</div>
### 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
<!-- blank line -->
----
<!-- blank line -->
Text
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Text
----
Text
</div>
</div>
----
## Emphasis: bold and italic
To display bold or italic text, wrap it into stars or underlines:
```md
This is **bold** and this is _italic_.
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is **bold** and this is _italic_.
</div>
</div>
----
## 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.
### Inline Links
We'd rather use inline links, such as `[Text to display](link)`, as they are easier to maintain.
Use relative URLs whenever possible.
### Identifiers
When there are **repeated** links across a single page, you can opt for using identifiers.
Place the identifiers at the end of the paragraph (or the section), arranging them in alphabetical order.
```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.
[This link][] (same as above), has a second pair of empty brakets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
[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.
[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
</div>
</div>
Important notes:
{: #links-important-notes}
- {: #note-identifiers} Identifiers **are not** case sensitive. They can be single words as `[link]` or `[multiple words too]`.
- {: #note-meaningful-links} 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.
- {: #note-deadlinks-checker} Check for broken links: <http://www.deadlinkchecker.com/>
----
## 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.
**Important:** always leave a blank line between the paragraph or heading and the subsequent list!
If you don't, the list will not render.
{:.alert .alert-info}
### Ordered lists
Ordered lists are pretty easy to create. Couldn't be more intuitive:
```md
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
3. Sub item three
2. Item two
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
3. Sub item three
2. Item two
</div>
</div>
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
Paragraph:
1. Item one
1. Sub item one
1. Sub item two
1. Item two
1. Item three
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
1. Item one
1. Sub item one
2. Sub item two
1. Item two
1. Item three
</div>
</div>
### Unordered lists
Unordered lists are very easy to create too:
```md
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
</div>
</div>
### 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_
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
- 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_
</div>
</div>
----
## 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]
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
[![An awesome example image](/images/about-gitlab-com.png "Hello World")*My caption*][about.gitlab.com]
</div>
</div>
**Important notes:**
{:#images-important-notes}
- {: #image-shadow} Apply [shadow](#shadow) to your images!
- {: #image-requirements} All images must be placed [under `/source/images/`][source-img], in an appropriate directory. Only screenshots
and public domain images are permitted.
- {: #image-alt-text} 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.
- {: #image-filename} 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.
- {: #image-title} It's also recommendable adding an image title, as the "Hello World" exemplified above.
----
## Videos
There are two ways of displaying videos: within HTML5 `<video>` tags and within `<iframe>` tags.
### Display videos from YouTube
This method works for YouTube videos and any other embed video within an `<iframe>` tag.
1. Copy the code below and paste it into your markdown file. Leave a blank line above and below it
1. Go the video URL you want to display
1. Click on "Share", then "Embed"
1. Copy the `<iframe>` source (`src`) URL **only**, and paste it replacing the `src` below:
```html
<!-- blank line -->
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
<figure class="video_container">
<iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
</div>
</div>
### Display other videos
This method works for any video uploaded to somewhere retrievable from the internet from a URL, or from a relative
path like `path/to/video.mp4`.
1. Read through the [w3schools HTML5 video guide][w3-video], or the [MDN `<video>` guide][mdn-video].
1. Record or export the video in these three formats to achieve cross-browser and cross-device
compatibility: `.mp4`, `.ogg` and `.webm`.
1. Get the URL for your video
1. Choose an image to use as a poster
1. Copy the code below and paste it to your file
1. Replace the `src` URLs for your video URLs
```html
<!-- blank line -->
<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="path/to/poster_image.png">
<source src="path/to/video.mp4" type="video/mp4">
<source src="path/to/video.ogg" type="video/ogg">
<source src="path/to/video.webm" type="video/webm">
</video>
</figure>
<!-- blank line -->
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="/images/default-blog-image.png">
<source src="html5-demo.mp4" type="video/mp4">
</video>
</figure>
</div>
</div>
_**Note:** in case you don't have all formats recommended by **w3schools**, you can use just one of them,
but your video most likely won't be supported in all devices and browsers. The video above (`.mp4` only)
worked on Mozilla Firefox for OS X, Android, and Windows, and on Chrome for Android and for Windows.
But it may not work on other devices/browser, such as Chrome for OS X and iOS, or Safari.
In fact, the best option is using YouTube or Vimeo embed videos in `<iframe>` tags._
{: .note}
----
## Table of Contents (ToC)
With Kramdown, creating a Table of Contents is the easiest thing ever! The automatic ToC will include every heading in
the document, unless you don't want it to be included. You do not need to add anchors individually to every title. This is
an automated process.
```md
----
## On this page
{:.no_toc}
- TOC
{:toc}
----
```
As always, leave a blank line before and after the markup. Note that there are four dashes beginning
and closing the block, which is not required, but recommendable for keeping the same standards through about.GitLab.com.
The heading "On this page" can be adapted to your case, e.g., "In this tutorial", or "In this guide", etc. It's not required
either, but recommended.
The markup `{:.no_toc}` is used every time you don't want to include a heading into the ToC. Just add
it right below the heading, and it won't be included into the ToC. In fact `no_toc` is a
[custom class](#classes-ids-and-attributes), as described later in this guide.
The **output** ToC can be found at the very beginning of this page.
Alternatively, you can use ordered ToC too, displaying numbers at the beginning of the list. Just use the markup for
ordered lists and Kramdown will be smart enough to understand what you want:
```md
1. TOC
{:toc}
```
----
## Tables
Tables for markdown are challenging. So, we have two possible approaches: use markdown markup whenever possible,
but if you need pretty advanced table layouts, you are free to add them in HTML markup instead.
> _Markdown is not a replacement for HTML, or even close to it. ([John Gruber][daring-quote])_
{: #quote}
As explained by John Gruber, the creator of markdown, it has not been created to replace HTML,
so there are situations we can't run from using HTML. With complex tables, that's the case.
The following table has a header (first line), then markup to define the desired alignment (dashes and colons),
then the table body. You can go forward and add a separator to create subsequent table bodies.
However you prepare your table, its design will depend upon the CSS styles defined for them.
The last markup `{: .custom-class #custom-id}` **can** be used in case you want to attribute to
the `<table>` element a [custom class and/or a custom ID](#classes-ids-and-attributes).
```md
| Default aligned | Left aligned | Center aligned | Right aligned |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell | Third cell | fourth cell |
| Second line | foo | **strong** | baz |
| Third line | quux | baz | bar |
|-----------------+--------------+-----------------+----------------|
| Second body | | | |
| 2nd line | | | |
|-----------------+--------------+-----------------+----------------|
| Third body | | | Foo |
{: .custom-class #custom-id}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
| Default aligned | Left aligned | Center aligned | Right aligned |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell | Third cell | fourth cell |
| Second line | foo | **strong** | baz |
| Third line | quux | baz | bar |
|-----------------+--------------+-----------------+----------------|
| Second body | | | |
| 2nd line | | Hello World | |
|-----------------+--------------+-----------------+----------------|
| Third body | | | Foo |
{: .custom-class #custom-id}
</div>
</div>
<!-- ANOTHER CHANGE NECESSARY TO ADD TO CSS ^^ -->
Certain tools can help you to create your own complex table if you need merging lines or columns,
and more advanced layouts. This is a [Table Generator] that perhaps can help you out.
Note that the bars, spaces, and dashes were used symmetrically above just for providing a nice
view of the table markup. The symmetry is not required.
Read through the [Kramdown syntax guide][kram-tables] on tables for further information.
----
## Code blocks
There are a few options for displaying code blocks with Kramdown. Most of them use backticks ``` ` ```.
### In-line
This is an ``` `in-line` ``` code block.
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_In-line_
This is an `in-line` code block.
</div>
</div>
### Fenced
```
def hello
puts "Hello world!"
end
```
_Fenced Highlighted_
```ruby
def hello
puts "Hello world!"
end
```
or
```
def hello
puts "Hello world!"
end
```
{: .language-ruby}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Fenced_
```
def hello
puts "Hello world!"
end
```
_Fenced Highlighted_
```ruby
def hello
puts "Hello world!"
end
```
or
```
def hello
puts "Hello world!"
end
```
{: .language-ruby}
</div>
</div>
### Indented
Add 4 white spaces before every line:
def hello
puts "Hello world!"
end
_Indented Highlighted_
def hello
puts "Hello world!"
end
{: .language-ruby}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Indented_
def hello
puts "Hello world!"
end
_Indented Highlighted_
def hello
puts "Hello world!"
end
{: .language-ruby}
</div>
</div>
### Nested
Add 4 white spaces before every line. This is used when you want to display a code block
within a code block.
```
def hello
puts "Hello world!"
end
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Nested_
```
def hello
puts "Hello world!"
end
```
</div>
</div>
### In lists
Indent the text of each item in 3 white spaces. Leave blank lines between the code block and the list items,
and ident the code block in 5 white spaces:
1. Item 1
1. Item 2
```ruby
def hello
puts "Hello world!"
end
```
1. Item 3
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
1. Item 1
1. Item 2
```ruby
def hello
puts "Hello world!"
end
```
1. Item 3
</div>
</div>
----
## Blockquotes
Blockquotes are good resources to mentioning someone else's quotes, like we did [just above](#quote).
Also, can be used to emphasize a sentence or a small paragraph.
```md
> This is a blockquote.
> On multiple lines.
That may be lazy.
>
> This is the second paragraph.
----
> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
>
> * lists too
>
> and all other block-level **elements**.
>
> Even code blocks:
>
> def hello
> puts "Hello world!"
> end
> {: .language-ruby}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
> This is a blockquote.
> On multiple lines.
That may be lazy.
>
> This is the second paragraph.
----
> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
> {:.no_toc}
>
> * lists too
>
> and all other block-level **elements**.
>
> Even a code block:
>
> def hello
> puts "Hello world!"
> end
> {: .language-ruby}
</div>
</div>
----
## Notes
```md
This is a regular paragraph.
**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is a regular paragraph.
**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}
</div>
</div>
----
## Comments
_Markdown markup_
```md
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.
```
_Regular HTML markup_
<!-- This is accepted as a comment too -->
{: .language-html}
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.
<!-- This is accepted as a comment too -->
</div>
</div>
----
## Anchors
Add an anchor anywhere with:
```
[](){: name="hello-world"}
Some text
```
Or simply use an ID:
```
Some text
{: #hello-world}
```
----
## Font Awesome
Yes, we can use fancy [Font Awesome] icons too.
_Regular_
```
### <i class="fa fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}
```
And you can go further, such as the following.
_Styled_
```
### <i class="fa fa-puzzle-piece fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple Puzzle Icon
{: #puzzle-purple}
### <i class="fa fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
_Regular_
### <i class="fa fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}
----
_Styled_
### <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple GitLab Tanuki
{: #tanuki-purple}
### <i class="fa fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}
</div>
</div>
When doing something like this to a heading, it's important give it a custom ID (e.g., `{: #puzzle}`),
otherwise the one automatically created by Kramdown will sound very awkward.
The class `fa-fw` is used when you want to display the icons as a list. They will be aligned, as well as
the text right beside them.
See live examples [on this post][ssgs-post], where the icons are used to illustrate the text.
-----
## Classes, IDs, and attributes
Defining CSS classes, and elements IDs and attributes with markdown is definitely something unusual (Kramdown magic!).
But yes, if you know how to use it, you'll love it! Check how easy it is to do that with Kramdown:
```
Paragraph
{: .class .class-1 .class-2}
Paragraph
{: #custom-id}
Paragraph
{: .class .class-1 #custom-id-1}
## Heading
{: .class .class-1 #custom-id-2}
Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}
## Heading {#hello}
List:
- {: .class} List item with custom class
- {:#id} List item with custom id
To a [link]{: #link}, in-line.
This is a [link][google-es]{:hreflang="es"} in Spanish.
[link]: https://google.com
[google-es]: https://google.es
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Paragraph
{: .class .class-1 .class-2}
Paragraph
{: #custom-id}
Paragraph
{: .class .class-1 #custom-id-1}
### Heading
{: .class .class-1 .no_toc #custom-id-2}
Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}
### Heading {#hello}
{: .no_toc}
List:
- {: .class} List item with custom class
- {:#id} List item with custom id
To a [link]{: #link}, in-line.
This is a [link][google-es]{:hreflang="es"} in Spanish.
[link]: https://google.com
[google-es]: https://google.es
</div>
</div>
### Special classes
#### Shadow
The CSS class called `shadow` should be used when your image edges are not clearly defined.
This happens when it has a white background or when it's a screenshot with text (for example,
a screenshot of our user interface). For example, this image can be mistaken as part
of the text:
![text screenshot](/images/handbook/marketing/markdown-guide-image-plain-text.png)
Now, if you apply the class `shadow` to the image, it's discretely highlighted from the text:
![text screenshot with box shadow](/images/handbook/marketing/markdown-guide-image-plain-text.png){: .shadow}
To do that, apply the class directly to the image by adding the markup `{: .shadow}` right after the image
markup:
```md
![image alternative text](/path/to/image.png){: .shadow}
```
#### Note
As [previously](#notes) explained, you can add the class `note` to paragraphs that
you don't want to call attention to:
**Note:** this is something I don't want to call attention to.
{: .note}
Markup:
```md
**Note:** this is something I don't want to call attention to.
{: .note}
```
#### Colors
Add a custom class to a heading or paragraph using the following special classes.
**GitLab Orange**
#### GitLab Orange Heading
{:.gitlab-orange .no_toc}
Markup:
```
### GitLab Orange Heading
{: .gitlab-orange}
```
**GitLab Purple**
#### GitLab Purple Heading
{:.gitlab-purple .no_toc}
Markup:
```
### GitLab Purple Heading
{: .gitlab-purple}
```
#### Text Align
By default, the text will always be aligned to the left. You have a few
options to customize it with custom classes:
- Center: `.text-center`
- Right: `.text-right`
- Justify: `.text-justify`
For demonstrations purposes, they are aligned
in an [alert box](#colorful-sections), but this can be
applied to regular paragraphs and headings.
**Align to the center**
Center-aligned
{: .alert .alert-info .text-center}
Alert box markup:
```md
Center-aligned
{: .alert .alert-info .text-center}
```
Paragraph markup:
```md
Center-aligned
{: .text-center}
```
Heading markup:
```md
### Center-aligned
{: .text-center}
```
**Align to the right**
Right-aligned
{: .alert .alert-info .text-right}
```md
Right-aligned
{: .alert .alert-info .text-right}
```
**Justify**
Justified
{: .alert .alert-info .text-justify}
```md
Justified
{: .alert .alert-info .text-justify}
```
----
## Mix HTML + Markdown Markup
Mixing HTML markup with markdown is something almost "unthinkable" to someone used to regular markdown.
And it's all over this document!
Use the following markup at the beginning of your document:
```md
{::options parse_block_html="true" /}
```
And feel free to mix everything up:
```
Something in **markdown**.
<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>
```
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Something in **markdown**.
<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>
</div>
</div>
You can close the markup parser tag at any point, if you want to:
```md
{::options parse_block_html="false" /}
```
----
## Colorful sections
To add notes and warning blocks into colorful boxes,
we are making use of Bootstrap's [panel blocks] and [alert boxes].
Colorful sections are applied for very specific purposes and must not be overused.
Use panels when your description contains more than one paragraph, or a
long paragraph. For single and short paragraphs, use alert boxes instead.
When using panels, make sure to add the HTML parser markup to the beginning of your document's body:
`{::options parse_block_html="true" /}`.
{: #html-parser}
Copy paste the following code according to what you want to present to the user
and replace only the description. The available colors are:
blue (`info`), green (`success`), amber (`warning`) and red (`danger`), as follows.
### Additional Information
Use the following code for **important notes** and additional information:
```html
<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">
NOTE DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My important paragraph.
{: .alert .alert-info}
```
Blue panels render like:
<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">
INFO DESCRIPTION
</div>
</div>
And blue alert boxes render like:
My important paragraph.
{: .alert .alert-info}
If you want the text inside the alert box to be blue as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-info {
color: rgb(49,112,143) !important;
}
</style>
```
### Warnings
Use the following code for warnings, like information that may have a different
result if not used correctly:
```html
<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">
WARNING DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My warning paragraph.
{: .alert .alert-warning}
```
Amber panels render like:
<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">
WARNING DESCRIPTION
</div>
</div>
And amber alert boxes render like:
My warning paragraph.
{: .alert .alert-warning}
If you want the text inside the alert box to be amber as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-warning {
color: rgb(138,109,59) !important;
}
</style>
```
### Danger
Use the following code for crucial warnings, like commands that result to loss
of data:
```html
<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">
DANGER DESCRIPTION
</div>
</div>
```
To apply to a single paragraph, use an alert box:
```
My danger paragraph.
{: .alert .alert-danger}
```
Red panels render like:
<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">
DANGER DESCRIPTION
</div>
</div>
And red alert boxes render like:
My danger paragraph.
{: .alert .alert-danger}
If you want the text inside the alert box to be red as well, we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones. Add the following `style` tag to the end of your file.
```css
<style>
.alert-danger {
color: rgb(169,68,66) !important;
}
</style>
```
### Do's and Don'ts
You can use the combination of green and red panels or alert boxes for "Do's and "Don'ts":
```html
<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">
THINGS TO DO
</div>
</div>
```
or, use an alert box:
```
TO DO.
{: .alert .alert-success}
```
Not to do:
```html
<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">
THINGS NOT TO DO
</div>
</div>
```
or, use an alert box:
```
NOT TO DO.
{: .alert .alert-danger}
```
By doing so, the green panels for "DO'S" will look like:
<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">
THINGS TO DO
</div>
</div>
or, if you chose an alert box:
TO DO.
{: .alert .alert-success}
If you want the text inside the alert box to be green as well,
we need to apply [custom styles](#styles)
to the markdown document. They will override the existing ones.
Add the following `style` tag to the end of your file.
```css
<style>
.alert-green {
color: rgb(60,118,61) !important;
}
</style>
```
And for your "DON'TS" within red panels will look like:
<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">
THINGS NOT TO DO
</div>
</div>
or, if you chose a red alert box:
NOT TO DO.
{: .alert .alert-danger}
### Custom alert panels and alert boxes
All the previously mentioned alert boxes and panels are available by
default by [Bootstrap]. If we want them in a different
color, we need [custom styles](#styles). At about.GitLab.com, we
can use the orange and the purple one, as follows.
When using panels, don't forget to add to the beginning of your file the
[HTML parser markup](#html-parser) to be able to mix HMTL + Markdown:
`{::options parse_block_html="true" /}`.
#### GitLab Orange Alert Panel
<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
Panel block markup:
```html
<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
```
#### GitLab Orange Alert Box
My text in an orange box.
{: .alert .alert-gitlab-orange}
Box block markup:
```md
My text in an orange box.
{: .alert .alert-gitlab-orange}
```
#### GitLab Purple Alert Panel
<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
Panel block markup:
```html
<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">
Text in markdown.
</div>
</div>
```
#### GitLab Purple Alert Box
My text in an purple box.
{: .alert .alert-gitlab-purple}
Box block markup:
```md
My text in an purple box.
{: .alert .alert-gitlab-purple}
```
### GitLab Webcast Alert Box
To be used in a CTA for webcast announcement in blog posts.
You can use it for other purposes as well. Use it together with the [HMTL parser](#html-parser):
<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}
[webcast-link]: #
```md
{::options parse_block_html="true" /}
<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}
```
----
## Styles
Yes, guess what?
This:
```css
<style>
.purple {
color:inherit;
}
.purple:hover {
color:rgb(107,79,187);
}
</style>
```
<style>
.purple {
color:inherit;
}
.purple:hover {
color:rgb(107,79,187);
}
</style>
Plus:
```
Hey! Hover the cursor over me and guess what?! :)
{: .purple}
```
Equals to:
<div class="panel panel-info">
**Output**
{: .panel-heading}
<div class="panel-body">
Hey! Hover the cursor over me and guess what?! :)
{: .purple}
</div>
</div>
And yes, the `<style>` tag is _in_ this very markdown file. Believe it or not!
----
## Embed documents
It's easy to embed Google Docs, Sheets, Slides, and pretty much everything that
provides an iframe to use with. The only thing you need to do is use the
following code inside your markdown file and replace the iframe from the document
you want to embed:
```html
<figure class="video_container">
<iframe IFRAME CONTENT></iframe>
</figure>
```
### Google products
For Google products, with your document opened, click **File** -> **Publish to the web**.
For example here's how Google sheets will look like:
![Google Sheets - File - Publish to the web](/images/markdown-guide/file-publish-to-the-web.png)
Choose **Embed**, check your settings, click on **Publish** and copy the `<iframe>`.
Then go to your markdown file and wrap the iframe into a `<figure>` tag with the
responsive `video_container` class, as shown [in the beginning](#embed-documents).
#### Google Sheets
Let's exemplify with this [simple spreadsheet]. Follow the info [above](#google-products) to find the iframe:
![Google Sheets - Embed iframe](/images/markdown-guide/embed-google-sheet.png)
Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the `<iframe>` with your own:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
</figure>
```
#### Output:
{: .no_toc}
<figure class="video_container">
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
</figure>
<br>
#### Google Slides
Let's exemplify with this [GitLab deck template]. Follow the steps [above](#embed-documents) to find the iframe:
![Google Slides - Embed iframe](/images/markdown-guide/embed-google-slides.png)
Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the `<iframe>` with your own:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/embed?start=false&loop=false&delayms=3000" frameborder="0" width="1280" height="749" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>
```
#### Output:
{: .no_toc}
<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/embed?start=false&loop=false&delayms=3000" frameborder="0" width="1280" height="749" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>
<br>
#### Google Docs
Embedding Google Docs is not a recommended practice. Prefer converting your document content
to markdown instead. If you need to embed it anyway, follow the same instructions and the same logic as
we presented for Google Sheets and Slides, wrapping the `<iframe>` with a `<figure>` tag:
```html
<figure class="video_container">
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
</figure>
```
### SlideShare
To embed from SlideShare, go to the document you want to embed and hit the **Share**
button located below the slides. Copy the code under **Embed** and place it
inside the `figure` tag.
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(138, 109, 59)
;"></i> Be careful to only include the iframe content and strip anything else.
SlideShare will also add some other information in the embed code which you
will have to remove, otherwise the markdown page will be broken.
{: .alert .alert-warning}
For example, let's say we wanted to include the slides from [Ivan's talk on
GitLab Pages][slideshare-ivan]. Copying the embed code and stripping everything
else except from the iframe, would result in this:
```html
<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>
```
<i class="fa fa-info-circle" aria-hidden="true" style="color: rgb(49, 112, 143)
;"></i> You can safely omit the `<figure>` tag since SlideShare's widget is
already responsive, but we are showing this that way in order to be consistent
with the rest of the handbook.
{: .alert .alert-info}
#### Output:
{: .no_toc}
<figure>
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe>
</figure>
----
## Embed Tweets
To add tweets to markdown, copy both `<blockquote>` and `<script>` tags
from the twitter post and paste it into your file. To make it look much
nicer, wrap the script into a `div.center` (created for this specific purpose).
**Important:** if you used the [HTML parser](#mix-html--markdown-markup) in your
post or page, you'll need to set it to `false` before the `div`.
{:.alert .alert-info}
{::options parse_block_html="false" /}
<div class="center">
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
<br>
Markup:
```md
{::options parse_block_html="false" /}
<div class="center">
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
```
For more than one Tweet, copy and paste all the code blocks from Twitter into one `div.center`:
```md
{::options parse_block_html="false" /}
<div class="center">
<!-- first tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
<!-- second tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
</div>
```
----
## Markdown Editors
Please use one of the following code editors to write in markdown, or another **code editor** of
your preference.
It is **not** recommend writing your document in a regular text editor, then copy-pasting to markdown,
as it most likely will bring some characters with a different encoding (non UTF-8), which will cause the
markdown to not render correctly.
In case you don't have a choice and need to import a text already written in a text editor, paste it
to your markdown file using **command+shift+V** on a Mac, or **control+shift+V** on Windows or Linux.
You might minimize the cause of trouble by pasting without format. But yet, is not guaranteed it
is going to work, so double check your HTML output.
_Regular Code Editors_
- [Sublime Text 3][sublime]
- [Atom]
_Markdown editors (type and preview simultaneously)_
- Markdown editors for Mac: [Mou], [iA Writer]
- In-browser markdown editor: [StackEdit]
If you're not used to writing markdown, those editors can be helpful. Check a screenshot below of a
file being edited on Mou. On your left, there's the markdown markup you're writing, and on your right,
a preview of the output. The preview won't be exactly as the final result, but it's a very good
approximation, which gives you a good idea on what you're doing while you type.
![Mou for Mac - screenshot of markdown doc write and preview][mou-screenshot]
[StackEdit] is awesome too, you can work on a markdown file even if you're alway from your computer,
or out of resources. It works from every major browser and saves automatically your work to Google Drive.
----
## Complementary Notes
{: #tips--tricks}
- Words must be separated by one single space only. Do not leave more blank spaces than the necessary,
they can render differently than the expected and can cause other issues.
- Do not leave blank spaces at the end of sentences.
- {:#jump-a-line} Always leave a blank line between markups, except between list items. Example:
---- (markup for horizontal line)
<!-- blank line -->
Paragraph.
<!-- blank line -->
Do not leave blank lines within list items:
<!-- blank line -->
- Item 1
- Item 2
- Item 3
{: .language-html}
- As explained [above](#headings), do **not** jump headings. Always do h1 &rarr; h2 &rarr; h3 &rarr; h4. Never h2 &rarr; h4.
- Prefer short titles and headings. Do not punctuate them (unless they require a question mark or an exclamation).
- Try not to punctuate list items, but if you do, be consistent and do that through all the list.
- If you have to mention a non-clickable URL, prefer using backticks: `http://an-example.com`.
- To add fancy emojis to your file, click `control+cmd+space` on your Mac and check the ⭐️ **magic**! ⭐️ Do not overuse them, please!
- If you are confused about any markup that you've found in this file, you can check its [`raw` file] for reference,
where you'll be able to see exactly how everything was written to produce the results you are seeing on this page.
## More
{: .no_toc}
Anything else you know of and is not described here? Any new magic? Any trick? Please contribute!
<!-- Identifiers, in alphabetical order -->
[`raw` file]: https://gitlab.com/gitlab-com/www-gitlab-com/raw/master/source/handbook/product/technical-writing/markdown-guide/index.html.md
[about.gitlab.com]: https://about.gitlab.com/
[alert boxes]: https://getbootstrap.com/components/#alerts
[atom]: https://atom.io/
[blog]: /blog/
[Blog Style Guidelines]: /handbook/marketing/blog/#styles-guidelines
[bootstrap]: http://getbootstrap.com/components/#alerts
[daring-quote]: http://daringfireball.net/projects/markdown/syntax#html
[font awesome]: http://fontawesome.io/icons/
[GitLab deck template]: https://docs.google.com/a/gitlab.com/presentation/d/1ux0yeJpJooWgq1_UROeAbbM3nNYFiF_iU26P3msPdzU/edit?usp=sharing
[gitlab-markdown]: https://gitlab.com/help/markdown/markdown
[handbook-writing]: https://about.gitlab.com/handbook/communication/#writing-style-guidelines
[iA Writer]: https://ia.net/writer/
[img-seo]: http://www.practicalecommerce.com/articles/77645-6-SEO-Myths-about-Alt-Tags
[kram-tables]: http://kramdown.gettalong.org/syntax.html#tables
[kramdown]: http://kramdown.gettalong.org/
[Lightweight markup languages]: https://en.wikipedia.org/wiki/Lightweight_markup_language
[Markup language]: https://en.wikipedia.org/wiki/Markup_language
[mdn-video]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
[middleman]: https://middlemanapp.com/
[mou-screenshot]: /images/markdown-guide/mou-screenshot-preview.png "Mou for Mac - Markdown Preview"
[mou]: http://25.io/mou/
[panel blocks]: https://getbootstrap.com/components/#panels-alternatives
[Professional Writing Techniques]: /handbook/product/technical-writing/#professional-writing-techniques
[Redcarpet]: http://git.io/ld_NVQ
[SEO Guide]: http://www.seobythesea.com/2012/01/heading-elements-and-the-folly-of-seo-expert-ranking-lists/
[simple spreadsheet]: https://docs.google.com/a/gitlab.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/edit?usp=sharing
[slideshare-ivan]: http://www.slideshare.net/creatop/how-to-use-any-static-site-generator-with-gitlab-pages
[source-img]: https://gitlab.com/gitlab-com/www-gitlab-com/tree/master/source/images
[ssg]: https://www.staticgen.com/
[ssgs-post-raw]: https://gitlab.com/gitlab-com/www-gitlab-com/raw/master/source/posts/2016-06-10-ssg-overview-gitlab-pages-part-2.html.md
[ssgs-post]: https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/
[stackedit]: https://stackedit.io/
[sublime]: https://www.sublimetext.com/3
[table generator]: http://www.tablesgenerator.com/html_tables
[visually-impaired]: https://gitlab.com/gitlab-org/gitlab-ce/issues/12797
[w3-video]: http://www.w3schools.com/tags/tag_video.asp
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com
[w3c]: https://www.w3.org/MarkUp/html-spec/html-spec_5.html#SEC5.4
[wrap]: /2016/10/11/wrapping-text/#do-wrap-it
source/posts/2016-01-26-call-for-writers.html.md
+ 3
− 3
View file @ 3c8f7b11
@@ -6,7 +6,7 @@ author_twitter: nearlythere
image_title: '/images/blogimages/write-gitlab.jpg'
---
 
Update: Please see our updated [Community Writers Program](https://about.gitlab.com/handbook/marketing/blog/community-writers/)
Update: Please see our updated [Community Writers Program](https://about.gitlab.com/handbook/product/technical-writing/community-writers/)
 
We’re opening our blog up to contributions from the community.
When you get published on our blog at [GitLab](https://about.gitlab.com/blog) you can earn $50 to $200 for technical articles.
@@ -37,7 +37,7 @@ What we're looking for...
- In-depth tutorials or opinion pieces of 1,500+ words.
 
 
Review [our call for writers](/community/writers) for the kinds of topics we're looking for.
Review [our call for writers](/handbook/product/technical-writing/community-writers/) for the kinds of topics we're looking for.
 
## New to GitLab? That's OK!
 
@@ -71,4 +71,4 @@ These are some ideas our team have in their wishlist. Do you see something you c
1. Publish.
1. Get paid.
 
Visit [our call for writers](/community/writers) for more information on how to get started.
Visit [our call for writers](/handbook/product/technical-writing/community-writers/) for more information on how to get started.
source/posts/2016-07-19-markdown-kramdown-tips-and-tricks.html.md
+ 6
− 6
View file @ 3c8f7b11
@@ -414,13 +414,13 @@ Follow [@GitLab] and stay tunned for the next post!
 
[about.GitLab.com]: /
[@GitLab]: https://twitter.com/GitLab
[boxes]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#colorful-sections
[classes]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#classes-ids-and-attributes
[boxes]: /handbook/product/technical-writing/markdown-guide/#colorful-sections
[classes]: /handbook/product/technical-writing/markdown-guide/#classes-ids-and-attributes
[CodePens]: https://codepen.io
[contribute]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/CONTRIBUTING.md
[docs]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#embed-documents
[docs]: /handbook/product/technical-writing/markdown-guide/#embed-documents
[font awesome]: http://fontawesome.io/
[guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[guide]: /handbook/product/technical-writing/markdown-guide/
[Handbook]: /handbook/
[handbook-post]: /2016/07/12/our-handbook-is-open-source-heres-why/
[identifier]: #
@@ -431,9 +431,9 @@ Follow [@GitLab] and stay tunned for the next post!
[news]: https://news.ycombinator.com/item?id=12091638
[responsive]: https://css-tricks.com/NetMag/FluidWidthVideo/Article-FluidWidthVideo.php
[SSGs]: /2016/06/10/ssg-overview-gitlab-pages-part-2/
[videos]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#videos
[videos]: /handbook/product/technical-writing/markdown-guide/#videos
[www-GitLab-com]: https://gitlab.com/gitlab-com/www-gitlab-com
[source file]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md
[source file]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/source/handbook/product/technical-writing/markdown-guide/index.html.md
 
<style>
.blue {
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment