The GitLab blog is managed by @rebecca the Managing Editor.
blog post.#content for questions, #content-updates for updates on most recently published articles.Mission statement: Create, curate, and elevate stories that increase awareness of the benefits of a single application for the entire DevOps lifecycle, as well as awareness of GitLab as a pioneer in all-remote work.
Please see Attributes of a successful blog post below for examples of stories that perform well on our blog.
The blog is not the permanent place for tutorials, which should live in the docs and should be linked to when relevant.
We follow the GitLab Workflow. At GitLab, everyone can contribute, and we encourage anyone to submit a blog post idea or write your own. Below are instructions on how to contribute to the GitLab blog.
If you need to publish a time-sensitive post, it is critical that you give the content team advance notice. Please follow the process outlined below:
Blog post template and applying the priority label. Even if you do not have a draft or a confirmed publish date, it's important to open the issue as far in advance as possible and ping @rebecca so she knows it is coming and can prioritize accordingly.Blog post merge request template for your MR and ensure it is set to close the associated issue automatically.Please assign first to @rebecca. If she is OOO, assign to @erica. If both are unavailable and you cannot wait until either returns, please assign to a member of the Technical Writing team. Where possible, select the technical writer who is listed for the most relevant stage group. If you need immediate assistance/review, find a technical writer who is online on Slack to request this directly. Regardless, be sure to specify any time contraints around getting the content reviewed and posted.
Continuous delivery mindset: With time-sensitive posts, don't wait to publish a post if you have enough information to go live. It's OK to publish a headline and paragraph to get the news out in a timely matter and add more details later (e.g. add more graphics, charts, etc.). We don't want to miss out on a news cycle because we're waiting for an image or supplementary information.
Inspired by error budgets used by Engineering.
Applied to the blog, error budgets incentivize forward planning and early communication of time-sensitive blog posts. This helps the Editorial team to minimize time spent on unplanned work, shuffling of the publishing schedule, or work that is subsequently wasted or does not serve our mission and vision, or the needs of our audience.
Each functional group is responsible for not exceeding an allowed budget of 15 points per quarter. The number of points given will depend on the severity of the impact to the team's workflow:
Where error budget points are incurred, a member of the Editorial team will apply the relevant label to the issue or merge request in question. Points will be totaled at the end of the quarter and communicated to functional groups who exceed their budgets, so that we can work together on solutions to prevent this in the future.
@rebecca a heads up that your post needs to go live on a specific day.@rebecca well ahead of time (a minimum of two working days before you expect to publish).You do not need approval to write for the GitLab blog, however if your proposed post does not align with the blog objectives and scope, the Editorial team may suggest that you submit your post to the GitLab Unfiltered blog instead. If you would like to write a post for the main blog, please follow the process outlined below.
Note: If you're planning to write a tutorial post describing how to do something with GitLab, please ensure that the relevant documentation exists first before you write a blog post about it. A blog post should not replace documentation, but should add more information, context, and color around a technical subject, linking back to the documentation for full instructions.
Blog post template.Blog post merge request template for your MR and ensure it is set to close the associated issue automatically.If you have a blog post idea but do not intend to write it yourself, simply label the issue blog post and the content team will review during triage.
Blog post ideas and proposals for Content Hack Day should be created in the Content Hack Day project. We keep these issues in a separate project because not all ideas and proposals that come from Hack Day will be worked on.
For follow-up posts to Pick Your Brain interviews with the CEO, as soon as an interview or livestream is scheduled, please open an issue in the gitlab.com/gitlab-com/www-gitlab-com project, using the PYB blog post template, and fill out the relevant information there.
The blog editorial team will assess the content of the post and decide how best to leverage it. This may mean publishing on the blog, on our Medium site, simply sharing the video on social, or something else.
Once agreed, the blog team will assign and communicate the expected publish date.
The Editorial team is responsible for triaging blog post issues and reviews the blog post queue.
priority will be added to the top of the planning list.In progress stage as they should already have a draft startedblog post: every blog post idea, proposal, draft, etc. MUST have this labelpriority: blog posts that should be worked on immediatelyPlanning/in progress: blog posts that are assigned to a member of the Content Marketing/Editorial teamReview: blog posts that are ready for an editorial reviewWaiting for author: blog posts that have been reviewed by the Editorial team and assigned back to the author to address feedback or approve for schedulingScheduled: Blog posts that have completed reviews and are scheduled for publishingGuest/Partner post: blog posts that are authored and submitted from a contributor outside of GitLabcustomer story: blog posts that include a customer interviewCEO interview: blog posts submitted by the GitLab CEO and require their subject matter expertiseContent hack day: blog posts that have been accepted from the Content Hack Day project.With the exception of time-sensitive announcements and news, we are aiming to have blog posts scheduled two weeks ahead.
The calendar below documents when posts will be published, as well as industry awareness days and anniversaries we may cover. Please bear this in mind when requesting a specific publish date for a post.
Please note that all dates are subject to change to accommodate urgent posts and announcements.
The Content Marketing team is responsible for increasing sessions on the GitLab blog month over month. We use data-driven insights to decide what to write on using the content marketing dashboard. In order to hit our goals, we aim to publish at least 3 blog posts that will garner 10,000+ sessions.
*From 2018 blog analysis conducted in 2018-10
Breakdown by category of "hits":
Qualifying story ideas:
Look for the following patterns:
Who and how to interview:
Pull information on all blog posts to document how many sessions each post received in the month, and how many sessions they received of all time. Categorize them by type, bracket, total sessions in month, total sessions to date, category, theme, and topic. Eventually add first touch point revenue data.
Search Google Drive for Blog Performance to find the appriopriate sheet to work from.
Column explanations:
In the event that we have a big announcement to make and the information must remain confidential until, use the forked project https://gitlab.com/gitlab-com/marketing/www-gitlab-com to prepare your merge request.
Occasionally, some blog posts are better suited to publishing natively by the author on LinkedIn, or on Medium. We reach slightly different audiences on these channels, and some content will get better exposure and reach if published there. If you submit a blog post and the content team decides it's a better fit for one of these, we will let you know. For now, we will treat this segmentation as an experiment, monitor the performance of different types of content on different channels, and apply our learnings. We may then be able to start planning content for specific outlets and commission stories accordingly.
We will promote anyone integrating with GitLab, even if we compete with them. It is very important to demonstrate to our customers that we do not lock them in.
If you are a partner or industry-adjacent third party who wants to write for our blog, please contact the Partner Marketing team before proceeding.
Blog posts concerning third parties or partners, whether they are to be published on the GitLab blog or externally, should be proposed to the blog editorial team before agreeing.
As a rule, any blog post, regardless of the author, should offer some informational, educational, or entertainment value to the reader. We do not publish material that is exclusively promotional in nature.
Official GitLab partners may use our CTA button and include promotional copy, however the blog post must still serve a function (informational or educational) other than simply promoting something.
For either type of guest post, the process and guidelines for publishing are as follows:
blog-post and guest/partner post.If the author of a guest post is not an official GitLab partner, they may link back to their website or own content with inline links, but may not include a CTA button or promotional copy.
We do not republish posts from other publications verbatim.
If you spot a tweet, post, or feedback anywhere detailing an interesting use case for GitLab which you think could make a good story, open an issue and ping @kimlock to help determine whether we should pursue an interview for a blog post or case study (we will not ask the original author to create something for us).
When we're doing a joint announcement and a partner wants to cross-post a GitLab article we have two requirements:
Crediting GitLab on a cross-posted article page is easy. The partner just needs to add a line like the following to their HTML source just above the article content:
<p>This post was originally published by GitLab on <a href="https://about.gitlab.com/path-to-original-article/">about.gitlab.com</a>.</p>
For example, if the URL for the original article is https://about.gitlab.com/2019/08/15/all-remote-is-for-everyone/ then the attribution source code would look like so:
<p>This post was originally published by GitLab on <a href="https://about.gitlab.com/2019/08/15/all-remote-is-for-everyone/">about.gitlab.com</a></p>
That would produce an attribution that looks about like this:
This post was originally published by GitLab on about.gitlab.com.
Adding a canonical link to a cross-posted article page's metadata is also easy. Just add a link element within the page's <head> element, add a rel attribute set to "canonical", and add an href attribute set to the original article URL.
For example, if the URL for the original article is https://about.gitlab.com/2019/08/15/all-remote-is-for-everyone/ then the link element should look like so:
<link rel="canonical" href="https://about.gitlab.com/2019/08/15/all-remote-is-for-everyone/">
Please see the publishing process before you get started.
To publish to the blog, you will need to create a merge request for the www-gitlab-com project with a file of your blog post content formatted in Markdown. Please read through the Markdown guide for reference.
If you like, you can start by drafting your post in a Google Doc (feel free to make a copy of this blog post template). Below are instructions for formatting the content of your file correctly. If you already have your content ready to go, you can jump ahead to see how to add your blog post file with a merge request.
The post frontmatter is the first part of any post. It is standard and cannot be changed, so please make sure to provide the correct information, and do not add nor remove anything from the default template. If you think one of the fields is unnecessary for your post, leave it blank and the editor who reviews your post may remove it.
---
title: "This is the post title"
author: Firstname Lastname # if name includes special characters use double quotes "First Last"
author_gitlab: GitLab.com username # ex: johndoe
author_twitter: Twitter username or gitlab # ex: johndoe
categories: company
image_title: '/images/blogimages/post-cover-image.jpg'
description: "Short description for the blog post"
tags: tag1, tag2, tag3
cta_button_text: 'Watch the XXX release webcast live!' # optional
cta_button_link: 'https://page.gitlab.com/xxx.html' # optional
guest: true # required when the author is not a GitLab Team Member
ee_cta: false # required only if you do not want to display the EE-trial banner
install_cta: false # required only if you do not want to display the 'Install GitLab' banner
twitter_text: "Text to tweet" # optional; If no text is provided it will use post's title.
featured: yes # reviewer should set
postType: content definition # i.e.: content marketing, product, corporate
merch_banner_destination_url: "/resources/ebook-single-app-cicd"
merch_banner_image_source: "/images/merchandising-content/benefits-of-single-app-cicd.jpg"
merch_banner_body_title: "Free eBook: The benefits of single application CI/CD"
merch_banner_body_content: "Download the ebook to learn how you can utilize CI/CD without the costly integrations or plug-in maintenance."
merch_banner_cta_text: "Learn more"
merch_sidebar_destination_url: "/resources/ebook-single-app-cicd/"
merch_sidebar_image_source: "/images/merchandising-content/benefits-of-single-app-cicd.jpg"
merch_sidebar_body_title: "Single application CI/CD"
merch_sidebar_body_content: "How to reduce costly integrations and plug-in maintenance."
merch_sidebar_cta_text: "Learn more"
---
More information about each field can be found below.
Please see below for instructions on sizing, formatting, and storing images.
For the cover, choose one from any public domain resource. Unsplash is our preferred resource for public domain images.
We try to keep images on the blog neutral in terms of gender, ethnicity, etc. This generally means avoiding using stock images of people. It is also better to avoid using images of people (for example, GitLab team members at an event) for the cover photo because the blog post title and description overlay the image, which can look too busy.
Please add a reference to the cover image source, owner, and license at the end of the blog post, even if it doesn't require attribution.
If you prefer, you can create an image.
In the absence of a custom cover image, you can use the default, but please only do so where there is genuinely no other option, or if making an important, operational announcement.
'/images/default-blog-image.png' (purple background and the Tanuki logo)Add featured: yes to the frontmatter of a post to create a featured post. The two most recent featured posts will be shown at the top of the blog in the featured section (even if more are tagged). To remove a post from being featured, remove the featured: yes line from the frontmatter.
Use only one of the following categories per post. Do not change the capitalization, spelling, or anything else, otherwise you'll create another category, which is something we don't want to do accidentally.
releases – release posts, security updates, patch releases, etc.engineering – technical, actionable content. Anything covering how to do something, use something, or solve a problem should fall under this categoryopen source – stories from or about our community, users, or the wider open source communityculture – posts about remote work, working together, or GitLab cultureinsights – industry, data, newsjacking, developer survey, etc.company – company or product announcements, policy changes, events, etc.security - security-related postsunfiltered – posts on GitLab UnfilteredWe're working on improving category pages and tagging, but for now you can find posts under the same category by navigating to
https://about.gitlab.com/blog/categories/category-name/. Dashes will be automatically added
to multi-word categories and all of them will be lowercased in the URL. For example, the
category "company" will be available under https://about.gitlab.com/blog/categories/company/.
Note that there's a CI test that checks for wrong or missing categories. If one of the above should change or a new category is added, don't forget to edit the following files:
Rakefile (search for CATEGORIES) - responsible for the CI testsource/includes/blog/category-nav.html.haml - responsible for the categories navbarsource/handbook/marketing/blog/index.html.md - the handbook which you're currently readingIf a category changes, you need to replace it in all posts. Here's a one-liner command you can run:
find ./source/posts -type f -exec sed -i 's/categories: old/categories: new/' {} \;
where old is the old category and new is the new one.
master and deployed. Ask a production engineer to help you.The description meta tag is important
for SEO, and is what appears on the blog index page. It is also part of Facebook Sharing and Twitter Cards. We set it up in the
post frontmatter, as a short summary of what the post is about. Description is limited to 150, otherwise the text will be cut off on the index page.
It is mandatory for all the new posts, and it has been included in the default post
frontmatter generated by the command rake new_post.
These are included to help readers find similar posts if they are interested in a particular subject. Tags appear at the bottom of each blog post, and clicking on a tag takes you to /blog/tags where you can view all tagged posts and browse by tag.
You can include as many tags as you like, separated by commas. Please only include tags from the following list, and note that they are case sensitive. If you think a tag should exist that isn't on this list, please leave a comment for the reviewer on your MR saying which tag you'd like to use and why it should be included.
The CTA entry is optional; if you don't need to add any CTA to the hero, just omit both entries, leaving the frontmatter without them. Do not include any UTM parameters in the link. Always wrap their values with quotes.
The final result is a red button over the cover image of the post.
In the below example, the following was included in the blog post's frontmatter in order to generate the CTA button.
cta_button_text: 'Watch the 8.16 release webcast live!'
cta_button_link: 'https://www.youtube.com/watch?v=iYPhXm8RlxI'
To not display the EE trial banner on the blog post, set ee_cta to false in the frontmatter. It is set to true by default, so there's no need to add ee_cta: true to the frontmatter. Only set to false on the rare occasion you have a strong reason to not display the banner (usually in the case of posts that are for developers and our open source community).
We use these to make it faster to track the effectiveness of different types of blog posts. There are three post type categories we use to differentiate blog content:
Use the postType frontmatter option to set the content definition.
We limit media embeds to the following providers:
We can now embed a CTA for readers to sign up for our newsletter directly from the blog post page. There are two different designs. Use the following:
<%= partial "includes/blog/content-newsletter-cta", locals: { variant: "a" } %>
Result:
OR
<%= partial "includes/blog/content-newsletter-cta", locals: { variant: "b" } %>
Result:
Note: this only works for blog post files with the extension .html.md.erb.
Consider adding pull quotes as click-to-tweet boxes, to encourage and make it easier for readers to share key points from your blog post. This only works for blog post files with the extension .html.md.erb.
To add a click-to-tweet box, copy the below partial and enter the text and author fields. If the author doesn't have a Twitter account you can use gitlab instead.
<%= partial "includes/blog/tweet", locals: { text: '', author: '' } %>
Example:
<%= partial "includes/blog/tweet", locals: { text: 'The Operations experience then should really just be that I go to work in the morning and see an email summary of what has happened, without me having to do anything', author: 'MarkPundsack' } %>
Renders:
{: .shadow}
These should be included by default on all blog posts.
You can see a live example of the merchandizing in this blog post: Why we created a Memory team at GitLab.
We may have different items to promote with these in the future, but for now these link to one eBook. Merch items are added by including all relevant fields in the frontmatter as shown in the example frontmatter above. You will also need to add the following items to the body of the blog post:
Add this line in between paragraphs at some point in the body of the blog post:
<%= partial "includes/blog/blog-merch-sidebar" %>
Add this line at the bottom of the blog post:
<%= partial "includes/blog/blog-merch-banner" %>
Note: These will only render if all the fields have been added correctly to the frontmatter as well. You can also view the raw file of our example post to see how all the necessary elements have been added to the frontmatter and body of the post.
Comments are present in all posts by default. Set it to false only if you have a strong reason to
do so (comments: false). They are our best source of feedback on posts.
Below are the two types of code blocks we commonly use on the blog. Find a number of other options in the Markdown guide.
We use this for short words or phrases included in a paragraph. For inline code, surround the word or code with single backticks (`).
Example:
This is an `in-line` code block.
Results in:
This is an in-line code block.
"Fenced" code blocks look like the block below. We use these for longer code snippets. To create a fenced code block, put triple backticks on one line directly above and one line directly below the code.
Example:
Results in:
this is my code block
here's another line
end
Blog images are stored in the source/images/blogimages/ directory. If your post contains many images, create a sub-directory for your post: source/images/blogimages/name-of-post/.
Tools, Adjust size and adjust the entry in the Resolution field. Preview will estimate what the resulting image size will be before you click OK to confirm.The only images accepted for about.GitLab.com are public domain images and screenshots. Whenever you choose an image which is not a screenshot, add a link to the original image to the merge request description and as an HTML comment:
<!-- image: image-url -->
Do the same for cover images, adding a link to the original image to the end of the post:
Cover image by [owner name and surname](link) on [Unsplash](link)
{: .note}
You can paste this from the box that appears on Unsplash when you have downloaded an image. For images not from Unsplash:
[Cover image](link-to-original-image) by [owner name and surname](link), licensed under [CC X](link-to-licence)
{: .note}
To add an image inline, insert the following into your markdown file, where you want the image to appear:
{: .shadow}
The alt text for your images should describe the content and function of your image for visitors using a screen reader.
There are new classes for sizing and positioning blog post images. They should be added to blog post images similar to how the shadow class is added already:
{: .shadow.small.left.wrap-text}
The new classes are grouped into:
Size
.medium: Display image 75 percent of page width.small: Display image 50 percent of page widthPosition
.left: aligned left (default).center: centered.right: aligned rightEffect
.wrap-text: Only applies to images that are positioned left or right. Makes text wrap around the image.
These classes are only applied for screens 992px wide and wider.
If a Position class is used without an Effect class then there will simply be empty space where the image isn't. Similarly, using a Position class without a Size class will have little-to-no effect.
Insert the following beneath an inline image to include a caption:
This is my image caption
{: .note.text-center}
This will look as below:
This is my image caption
For technical/tutorial posts, please illustrate your examples with code blocks or screenshots. Be consistent with your examples. E.g., if you are using a generic URL
to exemplify your steps domain.com, be consistent and keep it domain.com, throughout the post.
Important security point: Do not expose your personal details by using your real tokens or security credentials. Use placeholders such as [project's CI token] stub instead. Or blur them if displayed on screenshots.
Please see the Markdown Guide for instructions for embedding videos from YouTube and other sources.
If appropriate, please add a video credit, for example:
Video directed and produced by [Aricka Flowers](/company/team/#arickaflowers)
{: .note}
Animated GIFs are very useful to illustrate short dynamic processes, which might be easier to understand with this kind of resource. There are a few ways to create animated GIFs, one of them is using [Giphy Capture], a light-weight app for Mac.
Avoid GIFs with a huge file size, they will be difficult to load for users with bad internet connection. In those cases, you can either cut the GIFs in smaller pieces, or record a video, or use a sequential image.
Read more on Making Gifs in the Product Handbook.
If you create your own cover image, it should have the following proportions:
Try to have them harmonically aligned with the title, which overlays the background image in both cases. To crop the image, use the size of 1275x750 px. If you want to align the background image with the title overlay, use the widescreen proportion.
You can go about this a couple of ways: by adding a new file to /source/posts/ in the UI, or using the terminal on your own computer.
You should have an issue for the blog post you are writing. Go to the issue and click Create merge request.
Now you have a merge request! Please edit the title to be the same as your blog post title, but leave WIP in front.
Make sure you select the blog post template for your MR, as this contains some important tasks for you to complete.
You can assign the MR to yourself while you are working on it.
Click on the link to the right of Request to merge (this is the name of your branch).
Now navigate to /source/posts/ in the tree view, then click on the + dropdown menu and select New file.
Enter your filename using the format yyyy-mm-dd-name-of-your-post.html.md.erb. This will become the URL for the blog post so please keep that in mind and don't use something like my-blog-post-draft! 😄
Please do not include special characters, capital letters, or numbers (other than the date) in your filename as this can lead to issues with publishing and can break the link to your review app.
If you aren't sure when the post will be published, just choose an arbitrary date in the future – we will update it before publishing.
Now you can paste your post content into the window. If pasting from a Google Doc or another word processor, please make sure you convert it to plain text first. A quick way to do this is to paste everything into the URL bar of a browser, and paste it into your blog post file from there.
Note that there is no blank line at the top or lines in between your front matter items.
When ready, scroll down and enter a description of what you've just done in the Commit message box. Make sure the Target branch is correct (i.e. has the number and title of the issue for your blog post) then click Commit changes.
You will then see your added file. To go back to your MR, it's easiest to go to your MRs in your dashboard (this is why it's important to assign the MR to yourself when you create it). You'll find all MRs assigned to you in the top right corner of your screen.
In your MR, if you scroll down and go to the Changes tab, you should see the blog post file you added there.
To see a preview of your post as it will look when it's live, you will need to wait for the pipeline to pass. You can check its progress from the Pipelines tab. When it passes, you can click on View app near the top of your MR and it will open a new tab with your preview. Please check your review app before asking anyone else to review.
If you need to make changes to your file, you can edit it by clicking on the edit button, which will take you to the same interface as when you added your new file. Just make your changes, edit the commit message to say what you did and hit Commit changes.
When you're ready, assign the MR to a fellow team member to review your post. When they have reviewed and you've addressed any comments they had and resolved any outstanding discussions, please assign your MR and the corresponding issue to @rebecca to review.
You may find this video walkthrough helpful for creating your blog post MR from the UI:
You will need to be set up to edit the website locally in order to create your post this way. Please see GitLab 102 for instructions. If you're already set up:
git checkout mastergit pull to ensure your version of master is up to date with GitLab.comgit checkout -b new-branch-name (substitute new-branch-name with whatever you want to call your branch)rake new_post
Hit enter or return, then you'll be prompted to enter the post title. Type in the title exactly as you want it, for example "Hello World – I'm a new post" and rake will take care of the filename for you. Then you just open the file, fill out the front matter and start writing, or paste your (plain text) draft in from your Google Doc.
Most blog posts require a new cover image. You should upload your chosen image to the same branch as your blog post file, so that it is all included in the same MR. This means it will be published to the website simultaneously, and also allows you to preview your cover image in the review app.
When you have selected an image to use, save it on your computer, ensuring you don't include any capital letters, spaces, or special characters in the filename.
Now go to your MR and click on the branch name afterRequest to merge.
Navigate to source/images/blogimages/ in the tree view, then click on the + dropdown menu and select Upload file
Drag and drop or click to upload your image file, then enter a description of what you've just done in the Commit message box. Make sure the Target branch is correct (i.e. has the number and title of the issue for your blog post) then click Upload file.
To go back to your MR, it's easiest to go to your MRs in your dashboard (this is why it's important to assign the MR to yourself when you create it). You'll find all MRs assigned to you in the top right corner of your screen.
In your MR, if you scroll down and go to the Changes tab, you should see the blog post file you added there.
Make a note of the name of your image.
Scroll down to your blog post file and click on the pencil icon (Edit file button).
This will take you to the same interface as when you added your new file. In the frontmatter, look for this field:
image_title: '/images/blogimages/post-cover-image.jpg'
Change the image filename to the name of the image you just uploaded. Ensure that you keep the whole path the same (so, starting with /images/blogimages/). Now edit the commit message to say what you did and hit Commit changes.
Go back to your MR. If everything has been done correctly, when the pipeline passes your review app should show the cover image as expected.
This is usually because the image filename and what you entered in the frontmatter do not correspond. Look out for typos in either the filename or in the frontmatter.
Make sure that the image path is correct (i.e. it begins with /images/blogimages/ – no missing slash at the front, no source before the first slash).
It often helps to look at the file of another recent blog post that is already live and compare it to your file to see if there are any discrepancies.
