Thoughtworks Arts Website

Code which powers thoughtworksarts.io.

Commands

grunt serve
grunt build --dist
grunt deploy

How to create blog or newsletter items

1. Create the markdown file

• Create a new md file in posts folder or newsletters folder.

• Title lengths should be between 2-3 lines, possibly 4 but certainly not 5 or more.

• Slugs should be created manually from the title, but trim them to keep them neat and readable.

2. Add text

• Use normal markdown, aside from the caveats explained below.

• If you are copying from hackmd, note that:

  • You can convert images in the ![Image Description](image-path.jpg) format to the correct format below.
  • For newsletters, flatten out all # headings to h2 like this: ## (it's just a much better representation of the content for web purposes)

3. Add the excerpt divider

• Add the string <!--excerpt-ends--> to separate the preview excerpt for the listings pages from the full article content.

• Here is an example of what a neat and inviting listing preview looks like, and here is the code behind it.

• As per the above example, use the following format:

   [first sentence]

   {% include image / youtube / vimeo %}

   [second sentence]

   <!--excerpt-ends-->

   [rest of content]

• To achieve this, sometimes it may be necessary to add the excerpt separator mid-paragarph. This is fine and supported as per this example.

4. Add images or downloads

• If needed, create corresponding subfolder in post images or newsletter images folder with matching name to the md file.

• Once you have that you can use the following code blocks to render images:

   Image with no caption, link or alt text:
   
         {% include image file='image.jpg'%}

   Image with caption, link and alt text:
   
         {% include image file='image.jpg'
            caption='Image Caption'
            alt='Alt Text'
            link='https://www.link.org/' %}

   Image with alt text only:
   
         {% include image file='image.jpg'
            alt='Alt Text' %}

   Image with display border hidden:

         {% include image file='image.jpg'
            alt='Alt Text'
            class='no-border' %}

5. Add video

• If needed, use the following code blocks to render video:

   Youtube:
   
      {% include youtube id='ytid123abc' %}

   Vimeo:

      {% include vimeo id='vmid123abc' %}

   With captions:

      {% include youtube id='ytid123abc'
         caption='Caption Text' %}

      {% include vimeo id='vmid123abc' 
         caption='Caption Text' %}

6. Check social preview

• By default, a social preview image will be pulled automatically from the first image, youtube or vimeo found on the post.

• You can check this by inspecting the sourcve and looking for the <meta property="og:image" content="/image.jpg" /> element (any relative URLs here are converted to absolute URLs on publishing.)

• If you want to override this image for this post, add an image property to the jekyll front mater, as in this example.

7. Verify after publishing

• Once the post is published, make sure it looks good on the live site.

• Make sure the social previews are working using the facebook and / or twitter validator tools.