Introduction

(UPDATED on 21 Apr 2021) This is a template for blog posts. This website is built from Gatsby framework and the way of styling is slightly different from HTML/CSS. You can write posts use markdown or/and HTML/CSS. A copy of this blog file is available here.
This article will guide you to setup a development environment, relevant steps for produce a blog post, and introduce you to useful syntax for styling the blog post and adding resources such as images, videos, and codes. You can also use Google Docs to write a post then share the link with us, we will take care of uploading for you. However, you'll also need to specify header section in your post as shown in step 2 of write a post section.

We're working on improving the process!

Setup

You probably want to install Gatsby so that you can test your contribution before submitting it. To do this you'll need to setup a gatsby development environment in order to preview the website. Otherwise, go to write a post section.

Installation

1. For Windows users, Download and install the latest Node.js version from the official Node.js website. For other OS visit here. (You might also need to download Visual Studio installer to install node.js development tools).

2. Install Git.

3. Install Gatsby CLI by running npm install -g gatsby-cli

4. Fork this repository and open up your Git Bash/terminal (and navigate to a directory you want to place the site) and run:

git clone https://github.com/yourusername/dataviz-hub2.git
cd dataviz-hub2
npm install      # install dependencies

5. Run gatsby develop. Now you can view the site at http://localhost:8000/. Any changes you made to posts locally will be updated instantly on preview. Press Ctrl + C if you want to stop the server running locally. If you're happy with your changes, you could also run npm run serve to make a production build and check everything is identical to the development version at http://localhost:9000/.

If you have cloned the repository a while a ago,
fetch the latest commits from origin repository:

git checkout development
git pull upstream development

Write a post

If you didn't setup, skip the following text and look at steps for writing a post.

Once you've setup, run gatsby develop. Now you can view the site at http://localhost:8000/. The website will be reloaded automatically on changes. Press Ctrl + C if you want to stop the server running locally. If you're happy with your post, you could also run npm run serve to make a production build and check everything is identical to the development version at http://localhost:9000/.

Steps on below assumed you've setup everything mentioned above.

1. Make a new directory under the /content/blog/ directory, make sure the directory name is of the format 2020-06-12-my-blog-title (a YYYY-MM-DD date followed by some text). If you didn't setup, create the directory anywhere you wish to.

2. Create a file index.mdx (or with .md extension, but we recommend use .mdx because it’s a superset of Markdown syntax that also supports importing, exporting, and JSX. learn more about mdx).

   • At the very beginning of your index file, you have the following properties to specify in the header:

---
title: "This is a template for posts"
author: ["A", "B"]
date: "2020-03-06" # please use Y-M-D format required by mdx syntax, if the post belongs to "Events" category, then probably use the event date rather than the written date
description: "Shown at blog page"
category: "Articles" # use pre-set categories: "Articles", "News", "Tutorials", "Events"
tag: ["SomeTag", "AnotherOne"] # make sure tags & cate are capitalised
thumbnail: ./image.jpg # an image to use for your post's thumbnail
template: # optional, if set to "custom", you would need to design your own post page except from header and footer of the website.
featured: true # optional, Set it to true if you want to show the post on home page
disableTOC: false # optional, set it to true if you wish to disable the default Table of Contents
d3: ["file1.js", "file2.js"] # optional, use to include your d3 documents
---

• Wrap properties with triple hyphens. Use double quotation marks for all text, use square brackets in properties with two or more items.

• Then add content to the file, read next section and beyond to know more about how to style your post.

• (Compulsory for your first post): On first time you're required to add your name and avatar to the file author.json located at dataviz-hub2/src/data, otherwise author info will not be shown on the post (and the website produce errors). Format:

...
},                              // Make sure you've added comma after the previous right curly bracket
{                               // Start with left curly bracket
  "name": "New Author",         // The exact same name you've put in mdx file, use same name for all mdx file consistently
  "avatar": "../images/author/default.jpg",    // If you want to add your own avatar, place it under the /src/images/author folder and replace default.jpg with your image name and extension
}                               // No comma

3. Copy any other resources required for the post to the current directory. For example, if you want to include an image post.jpg then the file path for it would be /content/blog/yourdirname/post.jpg. Sections below will tell you how to embed images and videos.

4. Commit any changes you've made. If you didn't setup, see Upload via github.com section.

5. Now create a pull request. If it comes from a fork repository, read here. If it comes from a branch in origin repository, read here.

Upload via github.com

If you do not want to setup the environment, you can write a post by upload index.mdx file and any resources related to the post on Github too. To do this,

1. Go to repository and click on content/blog directory.

2. Click the Create new file button on the top right, and type folder-name/index.mdx in the name your file... box, this will create a new directory with the name - folder-name of your choice (make sure this name is not exists).

3. Copy contents of your local index.mdx file into the box below. Fill in all the details under the Propose new file section and submit. Now Github has already forked the project for you and you're on the Comparing changes page.

4. If you don't have any other files (images etc.) to upload, click on Create pull request button, complete the form and submit (and you're done). Otherwise ignore this and go to your own dataviz-hub2 repository.

5. Once you're in forked repository page, you'll see github has created a new branch patch-1 for you. Select this branch and go to the directory you've created e.g. content/blog/folder-name/.

6. Upload all neccessary files and commit directly to the patch-1 branch. Once this was done, go to https://github.com/researchdata-sheffield/dataviz-hub2 and click on Compare & pull request, complete the form and submit.

Table of content

If you have created headings using markdown syntax like below:

# table of content
Write something

## Subtitle
...

# Another Title
...

## Another Title - subtitle
...

then this website will automatically create a table of content list for you on the right hand side of the post.
If you would like to disable the table of content, simply insert the following line in the header section:

disableTOC: true

Styling

There are many ways to add styles to your md/mdx elements, in here we listed two methods to do this.

1. Use the style attribute as usual with slightly different syntax:

In HTML we normally style a div tag like this:
<div style="font-size: 25px, display: flex">
  Write something
</div>

-----------------------
In Gatsby (and React) we transform it into:<div style={{ fontSize: "25px", display: "flex" }}>  Write something</div>
For any declaration in HTML with hyphen,
in Gatsby we remove the hyphen and capitalise the letter after the hyphen.

2. This website has integrated tailwindcss framework therefore you can style elements by applying pre-existing classes directly in your HTML. Explore tailwindCSS to see available classes you can utilise.

// In Gatsby, class is replaced by className An example of using tailwindCSS

<p className="text-3xl text-gray-500 mb-24">TAILwindCSS</p>

text-3xl: text size with 3xl. text-gray-500: text color set to be gray with
transparency of 500 (50% probably). mb-24: bottom margin with size 24.

Output:

TAILwindCSS

Accordion

To use accordions in your post, you'll need to do something like this:

<Accordion allowZeroExpanded="true">
  <AccordionItem>
    <AccordionItemHeading>
      <AccordionItemButton> Section 1 </AccordionItemButton>
    </AccordionItemHeading>
    <AccordionItemPanel> Write Something </AccordionItemPanel>
  </AccordionItem>

  <AccordionItem>
    <AccordionItemHeading>
      <AccordionItemButton> Section 2 </AccordionItemButton>
    </AccordionItemHeading>
    <AccordionItemPanel>
      <p>You can also include other tags like paragraph and headings</p>
    </AccordionItemPanel>
  </AccordionItem>

  <AccordionItem>
    <AccordionItemHeading>
      <AccordionItemButton> Section 3 </AccordionItemButton>
    </AccordionItemHeading>
    <AccordionItemPanel>
      <p>Write something about section 3</p>
    </AccordionItemPanel>
  </AccordionItem>
</Accordion>

The output will be:

You have to start with <Accordion> tag and wrap everything within it. Use <AccordionItem> for each accordion you want to add, and use <AccordItemHeading> and <AccordionItemButton> together to produce the button and the heading. Then use <AccordionItemPanel> for your main contents. Each tag mentioned above has some properties you can specify, for example, only allow one accordion expanded at a time or expand first first accordion by default. Visit react-accessible-accordion to see what options are available.

Code

To add inline code, surround your code by single backtick.

`inline code`

For a code block, use triple backticks.

1```html
code block
1```

1 is for illustration, remove it in practice.

You can also specify what programming language after first triple backticks. To highlight lines, specify line numbers within curly brackets after triple backticks.

1```js{1-2,4,5,6}
code
1```

To add a title for your code block, insert :title=your-title-name just behind the language. Space is not allowed.

1```html{2}:title=My-title.html
Add a title for your code block!1```

D3.js

This website included the latest release of the D3.js library. Here is how you would include your D3 document in your post in two steps:

1. Place your D3 files under dataviz-hub2/static/d3

2. Add the following within the property list in the top of the index.mdx file:

   title: "This is an example document"
   ...
   d3: ["d3-filename.js", "more-file.js"]

   Items within squared brackets should be your file names, separate by comma if there are more than one files. If you want to inlcude external files (subject to approval), use the format "https://yourfile.address".

Embed well known services

You can embed many services (like CodePen, CodeSandbox, GIPHY, Instagram, Lichess, Slides, SoundCloud, Spotify, Streamable, Twitch, Twitter or YouTube) into blog posts by their URLs. Please ensure the URLs are wrapped by empty lines.

This is how you would embed a youtube video:

`video: https://www.youtube.com/watch?v=N5yRLFcbv4s`
or
https://www.youtube.com/watch?v=dKno6ojJd_Q

Note: you can't styling videos at the moment.

https://www.youtube.com/watch?v=dKno6ojJd_Q

Embed twitter:

https://twitter.com/OpenResShef/status/1255448310271356932
or
On Twitter, find the tweet you'd like to display.
In the top right-hand corner of the tweet, click the caret (∨) and select "Embed tweet".
Take the code you're given and copy it into your markdown page.

Note: when copying the embed code, copy only the blockquote section and not the script.

<blockquote class="twitter-tweet">
<p lang="en" dir="ltr">UKRI-funded researchers will know that the current open access policy only applies to journal articles &amp; conference proceedings - the new one will also apply 
to monographs, edited collections &amp; chapters 📚 (so particular heads up to our A&amp;H and social sciences researchers)</p>&mdash; Open Research TUoS (@OpenResShef) 
<a href="https://twitter.com/OpenResShef/status/1255448311953309702">April 29, 2020</a>
</blockquote>

To center the twitter card, use second option and wrap it with DIV with className "flex justify-center"

Embed codepen:

https://codepen.io/melvinidema/pen/ExVXzML

Embed CodeSandbox:

// Add "?view=split" to the end
https://codesandbox.io/s/ynn88nx9x?view=split

Files

To make a file available to readers, place the file under the post directory and add something like this:

<a href="./filename.pdf">Download</a>

Image

This is how you would embed add an local image (remember to add your images in the same directory of your md/mdx file):

![my image description](./temp.jpg "Here is the title after url")

Alternatively:

<img alt="my image description" src="./temp.jpg" title="hello" />

To add caption for image:

![my image description](./temp.jpg "Here is the title after url")
*This is my image caption*

Make sure you pressed SPACE key twice followed by ENTER key after the closing bracket, if successful captions should had become italic:

This is my image caption

Alternatively (so you can add style for images):

<img style={{marginLeft: "-100px", border: "solid 4px #00aeef", height: "300px", width: "550px"}} src="./temp.jpg" alt="image1" /><br />
<em>image-caption</em>

For images available online, use their url.

If you use the second way to add images, please don't forget to add alt text for each image to help users for some reason cannot view it (because of slow connection, an error in the src attribute, or if the user uses a screen reader).

Link

• URL within the website

  The post you're writing might be a part of your blog series, and if you wish to include link of previous posts (or any other part of the website) within a post, you'll need Link tag. To use Link tag:

  1. Make sure the file extension is .mdx
  2. Use to property instead of href, for internal pages you don't need to specify hostname (dataviz.shef.ac.uk):
     <Link className="text-gray-700" to="/blog">To blog</Link>

• Anchor within the post & URL outside the website

  Use a tag, add anchor keyword to the tag if the link is within the post.

  Anchor:
  <a href="#anchorLink" anchor>Link within the post</a>
  
  External:
  <a href="https://tailwindcss.com/docs/width">tailwindCSS</a>
  or [tailwindCSS](https://tailwindcss.com/docs/width)

TeX math

There are two ways to write math formulas and math symbols. For inline mode, surround your equation with $ to generate a math equation.

$a^2 + b^2 = c^2$

generates $a^2 + b^2 = c^2$.

For display mode, surround your equation with $$ and new-lines to generate a math equation.

$$
\frac{1}{\sigma \sqrt{2 \pi}} e^{-\frac{1}{2}(\frac{x- \mu}{\sigma})^{2}}
$$

generates