BCO-DMO blog

https://blog.bco-dmo.org

Getting Started

1. Create an author record in: _data/authors.yml

Writing a blog post

1. Create a post in _drafts folder like _drafts/my-first-post.md with the following template:

---
layout: post
type: BlogPosting
published: true
title: "title goes here"
subtitle: "an optional subtitle can go here"
description: "A callout text to be used in SEO. Think about the text you'd want in a Twitter share."
date: YYYY-MM-DD
lastModified: YYYY-MM-DD HH:mm:ss
author: [your key from _data/authors.yml]
category: news
tags: 
  - keyword1
  - keyword2
images:
  - id: goodtables_logo
    path: https://iiif.elifesciences.org/journal-cms/labs_experiment%2F2017-10%2Ftitle_goodtables-logo.png/full/2000,/0/default.jpg
    caption: <a href="https://goodtables.io" target="_blank">https://goodtables.io</a>
    url: https://goodtables.io
    max-width: 256px
    border: true
  - id: duplicate_row
    primary: true
    path: 2020-09-14-goodtables/goodtables_duplicate-row.png
    caption: "Goodtables noticed a duplicate row in an uploaded tabular data file."
    max-width: 512px
    border: true
---

Blog content starts. Callout text goes here<!--more--> Say more here

To view how your draft _drafts/my-first-post.md will look, go to https://blog.bco-dmo.org/drafts/my-first-post.

You can view a list of all drafts at: https://blog.bco-dmo.org/drafts/

Linking in a post

To create links in your post, use: {% include link.html url="url-goes-here" text="The text that should be linked" external=true %}

Example: {% include link.html url="url-goes-here" text="BCO-DMO website" external=true %}

To link the URL itself, you can omit the text attribute: {% include link.html url="https://www.bco-dmo.org" external=true %} will generate:

Linking to other blog posts

See https://jekyllrb.com/docs/liquid/tags/#linking-to-posts

Excerpts

Excerpts are snippets from the post that can be used elsewhere as callout text. From the template above, notice the <!--more-->. All blog content up to this comment tag will be captured as the blog's official exceprt, or callout text. This text appears in all blog cards from the homepage, section listings and tag listing pages. These excerpts are also included in the RSS feed of the blog.

Publishing a Post

1. Decide which category is the best fit. One of: [news, data-tools, insights, engineering]
2. Rename the post to _posts/YYYY-MM-DD-<desired-url-goes-here-using-dashes>.md (NOTE: _drafts was replaced by _posts
3. Save post
4. Create a new Release
   1. v(x).0 where (x) is incremented from the previous blog version number. For example, if the current version of the blog is v1.0, set release version to v2.0
   2. Set the Release Title to the title of your post.
   3. Click Publish Release

Q: Why do we need to publish releases?

Releases help us preserve the state of the blog so that if for any reason, we can recapture content at certain important points in the history of the blog. THis helps us mitigate unforeseen circumstances where content is accidentally deleted or moved.

6. Ensure the blog was successfully built

Post metadata

At the top of each post, is a section of metadata in between --- and ---

Metadata that does not change

• layout: post - tells the blog that this page is a blog post.
• type: BlogPosting - tells the webpage which schema.org type to use for SEO.

Metadata that you can change

• published
• title
• subtitle
• date
• lastModified
• author
• category
• tags
• images
• sameAs
• relations

published

Property	Value
Required	yes
Data Type	true or false

true means the blog post will appear on the website. false means the post will not appear - this includes drafts. Drafts with published: false will not appear in drafts.

title

Property	Value
Required	yes
Data Type	string

This is the title of your blog post.

subtitle

Property	Value
Required	no
Data Type	string

This is an optional subtitle for your blog post.

description

Property	Value
Required	no, highly recommended
Data Type	string

An, optional, but highly valuable field used for search engien optimization. It's used as the callout text in Twitter and LinkedIn shares. For that reason, keep the character count to around or under 200 characters.

date

Property	Value
Required	yes
Data Type	YYYY-MM-DD

This is the date your blog post was published. It should be set at the same time you set published.

lastModified

Property	Value
Required	no, but recommended if post is edited
Data Type	YYYY-MM-DD ss:mm:ss

This is the date your blog post was edited, and it tells search engines that your post needs to be reharvested. It should be set if you edit a published post. A sample value is: 2020-01-01 13:15:00

author

Property	Value
Required	yes
Data Type	string

This is the key from the _data/authors.yml file. For example, mike is the key if the author file has:

mike:
    name: Michael Jackson
    ...

category

Property	Value
Required	yes
Data Type	string
Accepted Values	news, data-tools, insights, engineering

Category determines which section the post appears in the blog.

images

Property	Value
Required	no, but recommended
Data Type	array of objects
Fields	id, path, primary, title, caption, url, max-width, border

Images are placed in assets/img/posts and they appear in the blog by using the following tag:

{% include image.html id="the-id-field-of-the-image-goes-here" position="right" %}

NOTE: position can be set to either right, left, or centered. Default : right.

Fields	Required	Data Type	Description
id	yes	string	An identifier used to reference the image from the {% include image.html %} tag
path	yes	string	Either the name of the file you uploaded to assets/img/posts or an absolute URL to an external image
primary	no	true or false	This tells search engines and social media which image to use as the its callout. Default: false
title	no	string	An optional title to display belwo the image and above anny caption
caption	yes	string	A short descriptionn of the image
url	no	URL	If you want the image to link off to another site or webpage
max-width	no	string	The size in pixels you wish to limit the image to. Example: 256px
border	no	true or false	If you want a border around the image

Example:

images:
  - id: goodtables_logo
    path: https://iiif.elifesciences.org/journal-cms/labs_experiment%2F2017-10%2Ftitle_goodtables-logo.png/full/2000,/0/default.jpg
    caption: <a href="https://goodtables.io" target="_blank">https://goodtables.io</a>
    url: https://goodtables.io
    max-width: 256px
    border: true
  - id: duplicate_row
    primary: true
    path: 2020-09-14-goodtables/goodtables_duplicate-row.png
    title: "Figure 1. Duplicate Row"
    caption: "Goodtables noticed a duplicate row in an uploaded tabular data file."
    max-width: 512px
    border: true

In the text, to place the Goodtables logo image, use: ```{% include image.html id="goodtables_logo" position="left" %}``

tags

Property	Value
Required	no, but recommended
Data Type	Array of strings

Tags are used to group posts by keyword. To list tags, format this value:

tags:
  - keyword1
  - keyword2
  - keyword3

Each keyword will create a new page. keyword1 can be seen at: https://blog.bco-dmo.org/tag.html#keyword1

sameAs

Property	Value
Required	no
Data Type	list

sameAs is used when the same blog post is also being posted by someone else. This field lets web crawler's know that the blog posts are the same. It alos puts links at the bottom of our blog posts to the other websites hosting the same post.

Structured as a list, use it like this:

sameAs:
  - https://frictionlessdata.io/blog/2020/02/10/frictionless-data-pipelines-for-open-ocean/

One hyphenated URL for each different website.

comments

Property	Value
Required	no
Data Type	true or false

You can disable commenting by setting comments: false.

relations

Property	Value
Required	no
Data Type	object

Fields	Required	Data Type	Description
url	yes	URL	The URL of the related resource
title	yes	string	The title of the page or resource being linked
description	yes	string	A description of why the URL is related to this post. Can contain HTML with links

relations is used when you want to include related links. This can be helpful when blogging about how to use ceertain software, tools, or data stadards and we want to provide links for readers and SEO.

Structured as a list of object, use it like this:

relations:
  - url: https://doi.org/10.1575/1912/25777
    title: Capturing Provenance of Data Curation at BCO-DMO
    description: A presentation given to the <a href="https://datacurationnetwork.org/" target="_blank">Data Curation Network</a> on why BCO-DMO chose declarative workflows
  - url: https://frictionlessdata.io
    title: Frictionless Data 
    description: The Frictionless Data project, created by the <a href="https://okfn.org/" target="_blank">Open Knowledge Foundation</a>, where you can find tutorials, tools and more

One hyphenated URL for each different website.

Resources

Need to upload Images?

Images for documentation can be uploaded here: How-To & Documentation Images

Jekyll + Liquid Templates + Github Pages

• http://jmcglone.com/guides/github-pages/

Markdown

• https://packetlife.net/media/library/16/Markdown.pdf
• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet