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 three 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>

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

<Zoom url="/assets/images/your-image.png" alt="Image alt text"/>

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.

Internal links can be added with "/" at the beginning of the link.

Example: [CKAN](/solutions/ckan)

External links should be added with proper https:// protocol at the beginning of the link.

Example: [My Link](https://www.linkdomain.com/something)

This verification will also ensure that all the external links are added with the target="blank" property applied, ensured that all external links open in a new tab.

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
description: "Case study description"
image: /assets/img/blog/image-name.jpg
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
tech:
  - tech1
  - tech2
usecases:
  - Internal Data Management
brief: Resolution component brief
problem: Resolution component problem
need: Resolution component need
solution: Resolution component solution
providers: 
  - Service provider 1
  - Service provider 2
client: Key facts component client
period: Key facts component work period
work: Key facts component product link
website: 1 
---

(Actual markdown blog content goes here)

The article layout is specifically used for Case Studies.

• authors, avatarUrl, industries, regions, services, usecases, tech and providers 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

• providers, client, period and work fields are used in the Key Facts component and are optional, but strongly recommended. You may include at least one of those fields for the Key Facts component to appear in the top of the case study with the available information. Their content should have the following:

  • providers: Service providers that executed the work (supports Markdown syntax). This is a list.
  • client: Client name with optional link (supports Markdown syntax)
  • period: Project period
  • work: Final product link, or Client's website in the case of undisclosed product(supports Markdown syntax)
  • services: No need to include if they are already present as a list.

• The website field is meant to be provided only if we have the Key Facts' work field link pointing to the Client's website instead of the final product. This is useful when the final product is undisclosed by Client's criteria. If you want to display the final product, just ignore this field. If you want to hide the final product but point to the Client's website, just add this field as show below:

website: 1

• brief, problem, need and solution fields are used in the Resolution component and are optional, but strongly recommended. All These fields support markdown syntax. If either one of these fields is missing, the component won't appear in the case study. Their content should have the following:

  • brief: Case study brief context of the case
  • problem: Actual problem needed to be solved by Datopian
  • need: Client needs based on the case context and/or agreements
  • solution: Solution provided by the Datopian in the work resolution

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.

Additional tips for Frontmatter Syntax

Frontmatter metadata syntax is very sensible. If a field has wrong syntax, the Flowershow render may misbehave. Here we have some tips to field types:

• String, or key: little or big text that supports markdown depending on the field.
• List, or array: List of strings.

All field types can be either surrounded by double quotes at both edges. Let's see some examples:

string: This is valid text.

string: "This is also valid text. We encourage double quotes, mainly if the text is long or needs Markdown syntax within it. Only a few string fields support markdown, though."

string: "This is valid text as I'm not closing the doublequote.

list:
 - Item 1 is valid.
 - "Item 2 is also valid, and also support double quotes, but don't support Markdown syntax."
 - Item 3 is invalid because I don't have double quotes at both edges"

Paths and Urls

Relative paths (for assets contained within the Datopian repository, mainly on the public folder) can be added for example, in the case of images. An initial slash is required for the adress to work. We can see an example below:

image: /assets/images/valid-url.png

image: "/assets/images/valid-url.png"

image: assets/images/invalid-url.png

Key Facts Component

The custom 'Key Facts' component provides the reader with the crucial information related to the case study. It will appear in the top of the case study if you provide the needed metadata in the frontmatter section:

providers: 
  - provider1
  - provider2
client: Client name with optional link (supports Markdown syntax)
period: Project period
work: Final product link, or Client's website in the case of undisclosed product(supports Markdown syntax)
services: No need to include if they are already present.

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. Provide it in the Frontmatter metadata and format it as follows:

brief: Case study brief context of the case
problem: Actual problem needed to be solved by Datopian
need: Client needs based on the case context and/or agreements
solution: Solution provided by the Datopian in the work resolution

Main Technologies & Tools Used Section

Here, we need to provide a list of the main technologies and tools used in the project. The available techs are displayed inside of the tech icons folder in the private website repository. Insert them in Frontmatter metadata as the following:

tech:
 - tech1
 - tech2

To add a new technology from your case studies:

1. Add an image to the tech icons folder with PNG format and case sensitive technology name.
2. Update your case study frontmatter with the proper technology name in the list, as the example above.
3. After the changes, the actual website deployment will be built again. Your new technology should appear in the Main Technologies & Tools Used Section.

Tags field

The tags field is optional and can be applied in any markdown page for Datopian website search indexing purposes. It's built so the user can add any tag that won't appear anywhere in the site, but can be used in the Search feature. This field should be provided as a list and formatted as the following:

tags: 
 - tag1
 - tag2

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 data portal for proper display and categorization. Below is a template for the Frontmatter 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

Search

The majority of the metadata fields for Case Studies, Blog Posts and Data Portals are used as keyword and keyword lists for the Datopian website Search feature. Therefore, although many of the fields are optional, we encourage the content publisher to embed as many metadata is feasible to ensure that we have the search feature to be as thorough as possible.

Here we have a list of properties that are used by content pages that are being read by the Search feature:

• Case Studies:

  • title
  • seotitle
  • description
  • industries
  • regions
  • usecases
  • services
  • description
  • brief
  • problem
  • need
  • resolution
  • providers
  • client
  • work
  • period
  • tech
  • tags

• Blog Posts:

  • title
  • seotitle
  • description (automatically fetched)
  • tags

• Data Portals:

  • title
  • seotitle
  • description
  • features
  • services
  • impact
  • tags