Skip to main content

Adding posts to the DocuHub Blog

This page explains how to add new posts to the DocuHub Blog's feed as a developer.

If you're a researcher looking to submit a blog post, you may want to consider filling out the Blog Post Request Form instead.

info

Please remember that blog posts submitted to CIROH DocuHub should discuss projects that make use of CIROH's cyberinfrastructure.

Adding posts manually​

Before continuing, you may want to set up a local environment for DocuHub. Please see the "Major Edits" section of the Working with the DocuHub Repository page for more information.

All DocuHub blog posts are written in the markdown format, with the extension .md. As such, they're compatible with all of the typical markdown syntax. Among other things, you can italicize text with *one asterisk on either side*, write bold text using **two asterisks**, or create subheaders by ## prefacing a line with two or three hash marks.

A markdown cheatsheet is available here.

Naming files​

To publish in the blog, create a Markdown file within the /blog/ directory. For example, the file at /blog/2019-09-05-hello-docuhub.md represents the first post written for this site.

DocuHub will extract a YYYY-MM-DD date from many patterns such as YYYY-MM-DD-my-blog-post-title.md or YYYY/MM/DD/my-blog-post-title.md. This allows for blog posts to easily be sorted and grouped by when they were published.

Formatting blog posts​

The top of the blog post should contain metadata, which is used to store information about your article. This includes:

  • Your article's title and description.
  • Your article's "slug", or the text used for its URL. Please be sure to only include letters, numbers, and dashes (-) in the slug!
  • Author information. This includes your name, a bit of information about yourself, a link to a website that represents you, and a photo.
  • Tags! These can be used to find articles relevant to a specific topic, so it's a good idea to several that are relevant to your article. This can include the tools discussed in your article, as well as the institutions or events where the relevant research was hosted. For some examples of relevant, helpful tags, check out the current blog posts.

This metadata is wrapped by three dashes (---) on the lines above and below it, and is parsed as YAML data. If you're not sure what that means, don't worry - the template below offers an example of the format.

Additionally, blog posts should include a line containing the text <!-- truncate --> directly below their introductions. This tells DocuHub where the blog post's introduction ends, which allows it to display the introduction as a short-form summary in the blog's feed.

Blog post template​

To use the template below, copy and paste it into an empty .md file in the /blogs/ folder.

---
title: Your article's title!
description: A one-sentence summary of your blog post.
slug: your-articles-title
authors:
  - name: John Doe
    title: Co-creator of Product 1
    url: <Your github product or external article link>
    image_url: <Author pic url>
  - name: Jane Doe
    title: Co-creator of Product 2
    url: <Your github product or external article link>
    image_url: <Author pic url>
tags: [hello, docuhub, nextgen]
hide_table_of_contents: false
---

The text above the truncate line below will be displayed as a
standalone summary of your article, so it's a great place for
a quick and informative introduction.

<!-- truncate -->

Below the truncate line, you can add the rest of your blog post!