Skip to content

Latest commit

 

History

History
195 lines (134 loc) · 9.56 KB

BLOGGING.md

File metadata and controls

195 lines (134 loc) · 9.56 KB
Raw

Writing and Publishing a Pulumi Blog Post

So you're interested in contributing to the Pulumi blog? Great! Follow these steps to make it happen.

Set Up Your Development Environment

If you haven't already, clone this repository and follow the instructions in the README to set up your environment and run the development web server.

Once you're able to run:

make serve

If you can browse the site locally at http://localhost:1313/ then you are ready to proceed to the next section.

If you get a build error like _index.md:1:1": plain HTML documents not supported, double check you are using the right version of hugo as described in README.md. (#1091)

Make a New Post

  1. Resist the temptation to copy-and-tweak an existing post! Instead, run the following command into the terminal (at the root of the project). This will generate a new file, including all the required frontmatter parameters.

    hugo new --kind blog-post blog/my-new-post

    This will create a minimal post browsable at http://localhost:1313/blog/. You'll find the new post's source file at content/blog/my-new-post/_index.md containing the set of Hugo front matter properties you'll need to get started:

    ---
title: "My New Post"
date: 2019-07-17T14:26:50-07:00
draft: true
meta_image: meta.png
authors:
    - joe-duffy
tags:
    - some-tag
---

    Feel free to adjust the title, authors (more on this below) and tags as appropriate. To change the post's URL, simply rename the folder containing _index.md; changing the folder name to my-awesome-post, for example, would result in a post ultimately published at https://www.pulumi.com/blog/my-awesome-post.

    Important

    The title will populate the <title> tag of the page, the <h1>, and the display value if it is linked to internally. This field has a strict 60 character limit because of SEO related limitations. If you would like to have a longer display title (i.e. the <h1> tag) then you will need to specify it by adding h1: Whatever title you would like to the front matter. If you would like to display different text on internal links than what the title value is, you can also specify a linktitle value. Both the h1 and linktitle values can be of any length. Below is an example of this:

    ---
title: This a Page Title
h1: This is the H1 for the page
linktitle: This is the link text
...
---

    Keep in mind that only posts dated prior to "now" (meaning the moment the build process begins) and not marked as drafts will published to production. The development server renders both future and draft content (so you can work on scheduled posts in advance), but the build process does not; see below for details on scheduling posts for future publishing.

  2. If you don't already have a TOML file in the team directory of the repo, create one now. For Pulumi employees, that file should look something like this:

    id = "christian-nunciato"
name = "Christian Nunciato"
title = "Software Engineer"
status = "active"

[social]
github = "cnunciato"
linkedin = "cnunciato"
twitter = "cnunciato"

    For community contributors, it's mostly the same, but with a status of guest, and a more informative title:

    id = "mikhail-shilkov"
name = "Mikhail Shilkov"
title = "Microsoft Azure MVP and early Pulumi user"
status = "guest"
...

    The social section, and the items within it, are optional.

    Once your team-member file's been created, update the new post's authors property to refer to your team member id string. If you're still running the development server, you should see the change reflected in the browser immediately.

Write Your Post

Posts are written in Markdown and rendered with BlackFriday, Hugo's default Markdown processor. GitHub's Mastering Markdown guide is a helpful syntax reference if you need it. You can also include HTML in your posts, if you need greater control over the output than Markdown can provide.

For formatting guidelines, see the Style Guide in CONTRIBUTING.md.

Code Blocks

There are a couple of ways to do syntax highlighing in Hugo, but we generally recommend code fences, along with an optional language specifier — e.g., for TypeScript:

```typescript
let bucket = new aws.s3.Bucket("stuff");
...
```

Additional languages are available as well.

Notes

Shortcode for a warning note:

{{% notes type="warning" %}}
**DANGER** Will Robinson!
{{% /notes %}}

Shortcode for an info note:

{{% notes type="info" %}}
Using Bastion hosts is a best practice.
{{% /notes %}}

Media

Inline Images

To add images to the body of your post, first place them within in the folder containing the post's Markdown file (e.g., at blog/my-new-post/platypus.png), then reference them relatively:

![The humble platypus](platypus.png)

Social ("Meta") Images

When you generate a new post, an OpenGraph placeholder image is included for you, and a reference to that image is added to the post's frontmatter as well, as its meta_image. The meta_image is meant to accompany the post in social previews (Twitter cards, unfurled Slack links, etc.) and on the Pulumi blog home page. It's optional, but recommended, as it can help to make your post more attractive and informative.

For best results, we suggest the following specs for the meta_image, largely based on Twitter's dev docs:

Aspect Ratio Recommended Size Format Background
2:1 1200×600 PNG Opaque (No Transparency)

Remember to replace the meta_image placeholder (or remove the property altogether and delete the placeholder meta.png file) before submitting your post.

Video

To embed a YouTube video, you can use Hugo's built-in youtube shortcode, which takes the video's YouTube ID, obtainable from its public URL on youtube.com:

{{< youtube "kDB-YRKFfYE?rel=0" >}}

For videos belonging to the Pulumi YouTube channel, you'll usually want to append the ?rel=0 query parameter as well (as above), which tells YouTube to limit the suggestions it makes at the end of a video to those from the same YouTube channel. Learn more about player parameters here.

Tweets

There's a Hugo shortcode for Tweets, too, which accepts a Tweet ID, accessible from its permalink:

{{< tweet 1147203941609984002 >}}

For more Hugo shortcode fun, go here.

Done? Submit!

When you're ready to submit your post for review, issue a Pull Request against the master branch of the repo, and the team will have a look. Once merged — provided its date has passed and its draft status is no longer true — the post will be deployed to https://www.pulumi.com/.

A Note on Dates and Scheduling for Future Publishing

If you'd like your post to be published at some future date or time, you have a couple of options.

Since the build process is triggered by (and so requires) a commit to master, you can either wait for the post's date to pass, remove its draft setting (or change it to false), and then merge it, or leave its draft property true, merge, then change the property to false once the date's gone by. If a post happens to get merged with draft: false and a future date, the resulting build will exclude the post, requiring a commit of some sort to occur after its date in order to trigger a build and get the post published.

For this reason, leaving the draft property true until you're actually ready to publish gives you an easy way to kick off a build when the time comes.

Publishing Check List

  • As mentioned, use the Hugo blog-post generator instead of copying another post: hugo new --kind blog-post blog/my-new-post
  • Drafts will not be published, so either set draft: false or or delete it.
  • Spell and grammar check. Consider using a service such as Grammarly.
  • Check for a break <!--more--> after the first paragraph, and ensure that your post's introduction looks right on the blog home page.
  • Check that your meta_image appears properly on the blog home page. Do not use animated GIFs for preview images.
  • Preview locally. Check formatting, links, and images for appearance.
  • Use the Twitter card validator to check the how the blog appears in a tweet (use the preview provided in the PR).