The Publication Process

Introduction

The purpose of the Publication process is to ensure that Datopian’s content production is informative, regularly scheduled and a good representation of the work we do.

Checklist

• Ensure published content - including language, links, image accreditation etc. - is accurate.
• Share with either @yoanapopova or @lucasb for review.
• Where the article is based on a client interview or case study, liaise with the client to ensure there is a common understanding around the publication content and that the material to be published has client approval.
• Publish the content on Datopian’s blog.
• Update Content Publication Master Spreadsheet.
• Add new key terms to the glossary.
• Post-publication client engagement including:
  • Informing the client of the publication.
  • Sending them the links to the various channels that the article has been published on.
  • Thanking them for their input.

Posting on the Blog

Blog posting necessitates familiarity with GitHub and Visual Studio Code. If you haven’t already downloaded Visual Studio Code, you can find it here. Working with this software requires you to do some basic coding, but you by no means need to be a programmer to learn how. Basic coding knowledge is sufficient to work with these platforms. Simply follow the steps below! We recommend looking at how other articles have been coded at each coding step to make sure you understand how to apply the instructions.

Navigating and Editing content within our GitHub Repository

1. Open the repository on GitHub. Click on the blue ‘clone’ button and copy the second URL.

2. Open Visual Studio Code and go to the Terminal tab at the top → select ‘New Terminal’. The terminal is the part of the software where you write instructions.

3. In the terminal, type in git clone followed by the copied link, like this: git clone https://github.com/datopian/next.datopian.com.git. Press Enter on your keyboard.

4. In the explorer tab on the left, find the blog folder (content/blog/) and right-click on it. Select New File. Name the file using the naming convention your-blog-post-title.md (Example: new-ways-to-use-open-data.md). Do not forget to add .md. This is the file you will use to create your article.

5. Now you need to upload your blog post (thumbnail/main image included) images to the blog folder. To do this, save the pictures to your device and name them (using dashes to separate words instead of spaces) and drag and drop it to the blog images folder in Visual Studio Code.

6. Now you need to upload any other photos for your blog post to Visual Studio Code. Staying in the explorer tab, go to "Public → Assets → Image → Blog → YYYY-MM-DD-your-blog-post.md ". Save the images you need to your laptop and drag and drop these into this folder (there should be lots of images already there).

Adding Metadata

Frontmatter is a tool that allows us to specify metadata at the top of our markdown files. We use a very specific syntax for this header, and then we write our actual content below it.

1. Go back to your-blog-post-title.md file and add the following code to the document (this should stay at the top of the document):

2. Fill out the relevant information. It should now look something like this:

---
layout: blogPost
title: Your blog post title
seotitle: Alternative title for search engines
created: yyyy-mm-dd
authors:
  - Author 1
  - Author 2
avatarUrl:
  - /assets/image/team/Author-1.jpg
  - /assets/image/team/Author-2.jpg
categories:
  - category 1
  - category 2
date: yyyy-mm-dd
tags: featured1, featured2, featured3, event, useful
image: /assets/img/blog/image-name.jpg
---

(Actual markdown blog content goes here)

The blogPost layout is used for Blog Posts.

All the metadata above is required for the blog post to display properly, with a few important standards:

• title: This is your blog post title

• seotitle: This is an alternative title that will provide search engine optimization (SEO) crawlers additional keywords. The idea of this field is to be different from the article default title.

• image: This represents the main image (featured image) of the blog post and the image that displays when the content is shared on social media. Should be an URL to the image path, e.g. /public/assets/images/blog/YYYY-MM-DD-your-blog-post/your-image.png

• authors, avatarUrl and categories are required fields, formatted as lists. Lists can have multiple values. The respective field values must respect this syntax (e.g. for authors):

authors:
  - Author 1
  - Author 2

• avatarUrl is the author's image address, that refers by default to "/public/assets/images/team/Your-Name-And-Surnames.jpg". You should upload the author image to that folder if it's not already available.

• The categories field is meant to be populated by one or more of these pre-set categories:

  • Company News

  • Team & Culture

  • Open Data

  • CKAN

  • PortalJS

  • Data

  • Data Management

  • Frictionless Data

  • Open Source

  • Useful Tools

• The tags field is the only optional field. When populated, should receive any of these values:

  • featured1, featured2, or featured3 to feature the blog post on the site's Featured Blog Posts section.

  • useful to display the blog post in the Useful Tools section.

  • event to feature the blog post in the Featured Event section of the portal.

• Without a tag, the blog post will appear as a normal blog post in the list as the last one, ordered by date.

Formatting

The blog post content should be written in markdown and have a .md extension. If it's inside of the blog folder along with other blog posts and has the correct extension and metadata, your blog will be automatically detected and published properly on the blog.

For more instructions in Markdown syntax, please follow this link.

Custom components

We have built-in React (Javascript JSX) components that can empower your blog post along with the markdown syntax. It's simple to add a component to the blog post, you don't need to know coding to do this.

To add a component, you just need to use the component inside of the MD file, like this:

<Component>
(Actual content goes here)
</Component>

We have 3 custom components that can be used both for blog posts and case studies. They are:

• Callout component, that should be used in the middle of the document like this:

<Callout>
(Actual content goes here)
</Callout>

• Quote component, that should be used in the middle of the document like this:

<Quote author="Author 1">
(Actual quote goes here)
</Quote>

• Resolution component, that should be used in the middle of the document like this:

<Resolution title="Resolution Title" problem="Problem" need="Need" solution="Solution">
(Description of the Resolution)
</Resolution>

Adding Links

Note: The process of adding links (standard and image links) to articles as described below is standard Markdown syntax. It's a widely used format and isn't specific to our system. Therefore, if you ever need more detailed information or help with other Markdown functionalities, we recommend referring to our Markdown guide. This guide provides detailed instructions and examples on how to use Markdown, including how to add lists, tables, code blocks, emphasis, and more.

Adding Standard Links

To add a standard link in Markdown, use the following syntax:

[Anchor text](URL)

Here's an example: 

[Datopian]([https://www.datopian.com](https://www.datopian.com))

In the rendered Markdown, this will appear as: Datopian. When this link is clicked, it will lead to the Datopian homepage.

Anchor text

The publisher is encourajed to provide anchor texts for all links in order to comply with the SEO best practices.

Links Connections

Making links to existing pages and articles in your portal makes it better connected and powerful for SEO. You can find smart keywords within the article and link them to actual information resource from the Datopian Portal.

Adding Images as Links

You can also turn an image into a hyperlink. Here's the syntax:

[![Alternative text](Image URL)](URL)

Here's an example: 

[![Datopian logo]([https://www.datopian.com/assets/images/layout/datopian-logotype.png](https://www.datopian.com/assets/images/layout/datopian-logotype.png))](https://www.datopian.com/)

In the rendered Markdown, it will display an image that, when clicked, leads to the specified URL. In this case, clicking on the Datopian logo will lead to the Datopian homepage.

Please note that the "Alternative text" is a description of the image that gets displayed when the image cannot be loaded, and it is essential for accessibility.

Extracting Images from Google Doc file

There might be instances where developers deliver the article in a Google Doc format, with embedded images. If you're a content publisher tasked with posting the blog post, you can follow the steps detailed below in order to extract the images from the

1. Open the Google Doc blog post
2. From the top menu, select "File".
3. In the dropdown that appears, hover over "Download", this will open another side menu.
4. From this side menu, select "Web Page (.html, zipped)". This action will download a .zip file of the entire document, including the images, to your local drive.
5. Navigate to the location of the downloaded .zip file on your local drive and extract it.
6. Once extracted, open the resultant folder. Inside you'll find a folder labeled "images". This folder contains all the images that were embedded in the Google Doc.
7. Now, you can proceed with uploading these images to the appropriate folder in the GitHub repository.

Embedding videos

How to embed a YouTube video

Embedding a YouTube video in a Markdown (.md) file is straightforward. Below are step-by-step instructions:

1. Go to the YouTube video you want to embed.
2. Below the video, click the "Share" button.
3. In the Share options, click "Embed".
4. A new window will open displaying the HTML embed code for the video. It will look something like this:

<iframe width="560" height="315" src="https://www.youtube.com/embed/VIDEO_ID" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

5. Copy the entire iframe code and paste it at the location in your file where you want the video to appear. The resulting Markdown document will look something like this:

# My Markdown File

Here's an interesting video I found:

<iframe width="560" height="315" src="https://www.youtube.com/embed/VIDEO_ID" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

I hope you find it as interesting as I do.

Note: Be sure to replace VIDEO_ID with the specific ID of the video you are trying to embed. Also, some Markdown renderers, such as the one used on GitHub, may not support HTML or specific HTML tags, such as iframe. Check the platform where you plan to display your Markdown file to ensure that it supports the HTML you're using.

On Github

Github supports embedding videos with .mp4 or .mov extensions.

1. Go to the YouTube video you want to embed.
2. In your GitHub Markdown file, drag and drop the video to the code editor. Check in the 'preview' tab it's style within the rendered markdown content.

How to embed certain timeframes of YouTube videos

Sometimes, you might want to include a certain clip from a youtube video in your article to demonstrate a point.

There are a few ways to embed a certain timeframe of a youtube video clip into a web page/ blog post. One option is to embed the whole video and simply set it up to start from a particular time when you hit play. Ie. when you click on the 'Play' button you are instantly directed to the part of the video starting at 2:33 minutes. This option isn't ideal because the viewer doesn't know at which point they should stop watching the video (and might be put off watching it if it is too long).

Another option is to crop the video using an online video cropping tool and then embed only the desired timeframe. This is arguably the best option and the one we will focus on here.

In order to do this, just follow these simple steps:

1. Copy the URL of the youtube video in question in our example we will use the URL of 'Introducing CKAN' video.
2. Go to Streamable.
3. Paste the copied URL into the input field and click on 'Go'.
4. Pick the time frame that you want by moving the little white circles to the wanted seconds and click on 'Create video'.

In our example we want to crop it from 03:01 - 04:28.

5. Click on 'Embed' and copy the code that appears in the pop up window. Select "Fixed size".

6. Voila! Paste in on your web page/ blog post and you are good to go.

Here's an example, taken from an introductory CKAN video featuring Anuar Ustayev:

Click here to watch the full video.

Image Requirements

The content publisher author's image should have a 1:1 aspect ratio proportions, as they are displayed in the portal within circular containers.

All the other image containers of the portal are made to render images with a 16:9 aspect ratio. That gives us standard resolutions such as 1280x720 or 1920x1080 recommended for main article images. It can be any resolution, though, as long as it’s calculated for 16:9 aspect ratio.

For the images inside of the article content, any resolution is accepted. But you should be cautious: Depending on the resolution of the image, it would be very tall and that can be an issue. Images that have a huge height should be dimensioned prior to posting them in the blog, having the ease of reading in mind.

Creating a Case Study

Navigating and Editing content within our GitHub Repository

1. Creating a New Case Study File: Start with Visual Studio open. Navigate to the explorer tab on the left. Find the case-studies folder (content/showcase/case-studies) and right-click on it. Select New File. Name the file using the naming convention case-study-post-title.md (Example: a-case-study-of-value.md). This is the file you will use to create your case study.

2. Uploading Case Study Images: Case studies are often accompanied by specific images (including a thumbnail or main image). You need to upload your images to the case-studies folder. To do this, save the pictures to your device using a descriptive name with dashes between words in place of spaces (for example: case-study-thumbnail.jpg). Once named and saved, create a folder inside of the case-studies image folder (public/assets/images/case-studies) with the naming convention of YYYY-MM-DD-your-case-study-title.md. Then, drag and drop them into your case study folder images folder in Visual Studio Code. Drag and drop the saved images into this folder.

3. Adding Additional Images: You may want to include other photos or visuals in your case study. To do this, first, save the necessary images on your device. Next, in the explorer tab, go to your case study post image folder going to "Public → Assets → Image → Case-Studies → YYYY-MM-DD-your-case-study-title".

Adding Metadata

Metadata is an essential part of setting up your case study for proper display and categorization. Below is a template for the metadata of a case study:

---
layout: article
title: Your case study title
seotitle: Alternative case study title for search engines
created: yyyy-mm-dd
authors:
  - Author 1
  - Author 2
avatarUrl:
  - /assets/image/team/Author-1.jpg
  - /assets/image/team/Author-2.jpg
industries:
  - category 1
  - category 2
regions:
  - Americas
services:
  - Data Engineering
  - CKAN Development
usecases:
  - Internal Data Management
image: /assets/img/blog/image-name.jpg
---
(Actual markdown blog content goes here)

The article layout is specifically used for Case Studies.

• authors, avatarUrl, industries, regions, services, services and usecases are required fields and should be formatted as lists. Lists can have multiple values. The syntax should be as follows (e.g. for services):

services:
  - Data Engineering
  - CKAN Development

• The industries field should be populated by one or more of these pre-set values:

  • Education
  • Energy
  • CKAN
  • Government/Public Sector
  • International Organization
  • Non-profit/NGO
  • Pharma/Biotechnology
  • Public Health
  • Smart Cities

• The usecases field should be populated by one or more of these pre-set values:

  • Data Catalog
  • Internal Data Management
  • Open Data Portal

• The services field should be populated by one or more of these pre-set values:

  • CKAN Development
  • CKAN Consultancy
  • CKAN Features
  • CKAN Hosting & Support
  • Data Engineering
  • Data Strategy
  • Digital Transformation
  • Open Data Portal
  • UX/UI Design

• The regions field should be populated by one or more of these pre-set values:

  • Americas
  • Europe
  • Global

Formatting

When preparing a Case Study, there are specific formatting standards to follow. To better understand this format, we recommend opening an existing case study file within the case-studies folder.

Key Facts Section

Begin with a custom 'Key Facts' section to provide the reader with the crucial information related to the case study. Format it as follows:

:::note{.key-facts}
<section>
<kf>
<div></div>
**Service providers:**  
(Datopian and any other provider involved)
</kf>
<kf>
<div></div>
**Client:**  
(Client Name)
</kf>
<kf>
<div></div>
**Services:**  
(e.g. Data Engineering, CKAN Development)
</kf>
<kf>
<div></div>
**Period:**  
(e.g. 2019 – 2021)
</kf>
</section>  
:::

Resolution Component

Every case study needs a Resolution component, which provides a summary of the project, the problem faced, the client's needs, and the solution provided. Format it as follows:

<Resolution
title="Brief summary of the project"
problem="The client was facing a specific scenario etc etc"
need="The client needed a comprehensive solution to etc etc"
solution="We developed a highly customized etc etc">
(Description here)
</Resolution>

Main Technologies & Tools Used Section

Here, we need to provide a list of the main technologies and tools used in the project. Format it as follows:

**Main technologies & tools used**  

<section className="tech-container">

<Tech tech="ckan"/>
<Tech tech="python"/>
<Tech tech="jsonld"/>
<Tech tech="jenkins"/>
<Tech tech="eks"/>
<Tech tech="aws"/>

</section>

Custom components

Please refer to the Posting on the blog custom components section for further details.

Image Requirements

Please refer to Posting on the Blog: Image Requirements for further details.

Adding a Portal to "Portals we've built"

Navigating and Editing content within our GitHub Repository

To add a new portal to the Data portals we've built page:

To add a Featured Portal

1. Create a new Data Portal file: Start with Visual Studio open. Navigate to the explorer tab on the left. Find the data-portals folder (content/showcase/data-portals) and right-click on it. Select New File. Name the file using the naming convention data-portal-title.md (Example: your-data-portal-title.md). This is the file you will use to create your data portal.

2. Uploading Data Portal Images: Data Portals are often accompanied by specific images (including a thumbnail or main image). You need to upload your images to the data-portals folder. To do this, save the pictures to your device using a descriptive name with dashes between words in place of spaces (for example: your-portal-thumbnail.png). Once named and saved, create a folder inside of the data-portals image folder (public/assets/images/data-portals) with the naming convention of data-portal-title. Then, drag and drop them into your data portal images folder in Visual Studio Code. Drag and drop the saved images into this folder.

3. Adding Additional Images: You may want to include other photos or visuals in your case study. To do this, first, save the necessary images on your device. Next, in the explorer tab, go to "Public → Assets → Image →Data-Portals→ your-data-portal".

4. With Visual Studio open, in the explorer tab on the left, find the components/showcase/data-portals.jsx file and double-click it. Inside this file, you should see a JavaScript object within the DataPortals() function:

export function DataPortals() {
  const portals =[
{
  	title: "Data Portal Title",
  	image: "/assets/images/data-portals/your-portal-title/portal-image.png",
  	href: "https://portal-address.org/",
  	description: "Data Portal X makes access easier for data etc etc",
},
{
  	title: "Another Data Portal",
  	image: "/assets/images//data-portals/your-portal-title/dept.ed_.gov_-1024x467.png",
  	href: "https://data.ed.gov/",
  	description: "Data.ed.gov centralizes access to the Department of Education's open data, featuring a custom frontend built on CKAN, enabling users to explore public data, documentation, and APIs.",
},
{...}
]

return(
{...}
)}

Here, portals is an array of objects, each representing a Data Portal that will be displayed in the gallery grid.

5. To add a new Data Portal, add a new entry to the portals array of objects, such as:

  {
   title: "Data Portal Title",
   image: "/assets/images/data-portals/your-portal-title/portal-image.png",
   href: "https://portal-address.org/",
   description: "Data Portal X makes access easier for data etc etc",
},

6. To add a new Data Portal, add a new entry to the portals array of objects, such as:

  {
   title: "Data Portal Title",
   image: "/assets/images/data-portals/your-portal-title/portal-image.png",
   href: "https://portal-address.org/",
   description: "Data Portal X makes access easier for data etc etc",
},

To add a portal in “More Portals” section

1 - Read the instructions in the above section. Create the folder in the data portals folder using the convention ‘your-portal-title’ in the folder’s name. Upload a thumbinal for your portal there. You don’t need to create a .md file for this.

2. To add a new Data Portal, add a new entry to the morePortals array of objects, such as:

  {
   title: "Data Portal Title",
   image: "/assets/images/data-portals/your-portal-title/portal-image.png",
   href: "https://portal-address.org/",
   description: "Data Portal X makes access easier for data etc etc",
},

Adding Metadata

Metadata is an essential part of setting up your case study for proper display and categorization. Below is a template for the metadata of a data portal:

---
layout: showcase
title: Your data portal title
seotitle: Alternative title for search engines
image: /assets/images/data-portals/image-name0.png
images:
/assets/images/data-portals/image-name1.png
/assets/images/data-portals/image-name2.png
description: Your description text
features:
Description of feature 1
Description of feature 2
services:
Description of service 1
Description of service 2
impact: Description of resulted impact of the project
---

(Actual markdown blog content goes here)

The showcase layout is specifically used for Data Portals.

• All of the fields above are required.images, features and services should be formatted as lists. Lists can have multiple values. The syntax should be as follows (e.g. for services):

services:
  - Data Engineering: Description of this service within the project
  - CKAN Development: Description of this service within the project

Image Requirements

Please refer to Posting on the Blog: Image Requirements