Help

This is a Meraki Post internal page, to help us with the common formatting guidelines, so as to ensure uniformity and quality throughout the site. This page may not be relevant to you if you’re a visitor. But if you’re curious, and would like to see what we do behind the scenes, have a look at the content below; be our guest!

Posts on this site are made using this beautifully simple lightweight markup language called Markdown (I know, Markdown markup sounds funny). This is so that you can use any text editor, including the good old Notepad, to write posts.

Jump to

  1. Tools you need
  2. Setup Markdown Writer
  3. The basics (using Markdown Writer)
  4. The basics (without Markdown Writer)
  5. General guidelines (using Markdown Writer)
  6. General guidelines (without Markdown Writer)
  7. Formatting paragraphs
  8. Formatting poem verses
  9. Cover image
  10. Subheadings
  11. Blockquotes
  12. Emphasis
  13. Other important entities
  14. Lists (numbered and unnumbered)
  15. Hyperlinks
  16. Pushing content to GitHub

Tools you need

  1. Atom by GitHub to write posts in a beautiful, flexible interface.
  2. RIOT by Lucian Sabo to compress images for the posts so things load superfast.

Atom packages

Atom packages are superchargers for Atom. You can get these packages by going to File > Settings and then selecting the Install tab. (To check if you already have a certain package, go to the Packages tab.)

Install the following packages:

  1. Markdown Writer by Zhuochun
  2. Git Plus by Akonwi Ngoh (not required if you’re not a keyboard shortcuts fan)

The basics

If you have Markdown Writer

Meraki Post’s repository has a friendly Markdown Writer configuration already in place. If you have Markdown Writer, your work becomes very easy.

  1. Press Ctrl + Alt + P and give Atom a second to open a pop-out.
  2. Fill in the name of the post–just the name of the book.
  3. Change the date in the pop-out to match the tentative publishing date of the post.
  4. Hit Enter.

Fill in just the following details (the rest, you’d see, are already filled):

---
subtitle: Name of the Author
author: Your Name
tags:
- tag1
- tag2
image: assets/postimages/imagename.jpg
---

If you’re not using Markdown Writer

  1. Every post you make is essentially a Markdown file, which looks like a text file.
  2. All posts must be placed in the folder, _posts.
  3. All drafts must be placed in the folder, _drafts.
  4. All posts you place in the _posts folder should be named like 2017-09-30-name-book.md.
  5. All posts should have the following frontmatter in the beginning of the file (including the three hyphens).
---
layout: post
title: Name of the Book
subtitle: Name of the Author
date: 2017-09-30
author: yourname
tags:
- tag1
- tag2
image: assets/postimages/imagename.jpg
---

General guidelines (if you use Markdown Writer)

  1. The title should be a full title, with proper capitalisation.
  2. The subtitle should be the full name of the author, appropriately capitalised.
  3. The author attribute here is for the author of the post, which is you. Write your first name, all in lowercase, such as, ram.
  4. Tags are important. Make sure you leave the tags: line empty, and list down the tags preceded by a hyphen and a space. Tags can have spaces. So, it’s OK to have a tag like historical fiction.
  5. Image is important, too. It is typically the image of the book cover. Compress the image, and store it under \assets\postimages as a JPG file. In the frontmatter, just append /assets/postimages/ with the image file name, along with its extension.

General guidelines (no Markdown Writer)

  1. When naming files, omit non-catch words. For instance, Alice in Wonderland would become, alice-wonderland; this is called slugification.
  2. The date should be in yyyy-mm-dd format, such as 2017-04-15.
  3. The filename would be a combination of the date and the title, separated by a hyphen, along with its extension, .md (for Markdown), such as 2017-04-15-alice-wonderland.md.
  4. The layout should be post, and only post.
  5. The title should be a full title, with proper capitalisation.
  6. The subtitle should be the full name of the author, appropriately capitalised.
  7. The author attribute here is for the author of the post, which is you. Write your first name, all in lowercase, such as, veena.
  8. Tags are important. Make sure you leave the tags: line empty, and list down the tags preceded by a hyphen and a space. Tags can have spaces. So, it’s OK to have a tag like historical fiction.
  9. Image is important, too. It is typically the image of the book cover. Compress the image, and store it under \assets\postimages as a JPG file. Add the link to that image here, replacing \ with /. Windows understands \, Jekyll understands /. If you’re using Markdown Writer, just append /assets/postimages/ with the image file name.
  10. Most importantly, don’t forget to enclose this content between two lines of three hyphens (---) each.

Here’s a complete sample to help you understand. Note that there’s no by before the name of the author.

---
title: The First Trillionaire
subtitle: Sapna Jha, translated by Alok Jha
date: 2017-05-20
tags:
- fiction
- thriller
image: assets/postimages/firsttrillionaire.jpg
author: ram
---

Formatting the posts

Formatting content is very easy with Markdown. Here are the different formats we have:

Paragraph

  1. Just type on, like you would on Word. Make sure you don’t make spelling or grammatical errors.
  2. Leave a blank line after the frontmatter.
  3. Leave a blank line after every paragraph.

Here’s an example:

tags:
- fiction
- thriller
image: assets/postimages/firsttrillionaire.jpg
author: ram
---

I'd come across this title back in 2016 when I chanced upon the site about the "Most compelling read of 2016". When I was one among the winners of the Goodreads Giveaway of this book, I was overjoyed! While I waited for the book, I went through the reviews of the book on Goodreads. At the time of checking, the book had 270 five-star ratings, out of 274. Unbelievable, but true.

Sure enough, after some days of eagerly waiting, I received the book, and I started reading it. And the journey began.

Notice the blank line after the frontmatter, and between the two paragraphs.

Poem verses

Poem verses require line breaks, and not paragraph breaks, when splitting lines. To achieve this, put a double \, at the end of each line you need a line break at, like so:

Mommy had a little calf.\\
Little calf.\\
Little calf.\\
Mommy has a little calf.\\
His nose is black as tar.

Remember not to add the \\ markup at the end of the last line of the stanza.

Cover image

Compressing the image is important.

Just copy-paste the following code. Liquid will take care of putting up the image, as long as you’ve specified the image in the frontmatter.

![Cover: {{ page.title }}]({{ site.baseurl }}{{ page.image }} "Cover: {{ page.title }}")

Subheadings

Subheadings are specified using #. A first-level subheading is written as # First Level Heading. A second-level subheading is written with two hashes, like ## Second Level Heading. The number of hashes denote the level.

The subheadings in our posts are all third level.

Also, ensure that there’s a blank line before and after the subheading. Here’s an example.

Not one of the most thrilling covers, I had to admit. But let's not judge the book just by its cover.

### Characters

The story primarily revolves around Shail, the protagonist, of course. In scenes where the protagonist is absent, the focus promptly shifts to the other important characters.

If you use Markdown Writer and like keyboard shortcuts, write the subheading text and press Ctrl + 3 for third-level subheadings.

Block quotes

Block quotes are your favourite formatting control from the Blogger Editor and Open Live Writer. This is used to produce formatting just how it is at the beginning of this page. In Markdown, it is very simple. Just precede the text with >. A space after > is optional. However, to make the style consistent, you may want to add a space after the >. Technically, that will have no effect on formatting whatsoever.

> Run as fast as you can and tell Gopal to come here with Dr Narayan. And also go and tell Mr Singh to come here. He stays next to me.

What you need to remember here is that if you want to separate block quotes, you need to leave an empty line between the block quotes that you want separated.

Emphasis

Emphasis usually is shown using italics in books. It is more about the kind of font we’re using. We use a serif font, called Crimson. In this case, it is good to use italics, since this font has real italics, and they’re distinct from the roman (normal) style.

To emphasise any text, wrap it between two _, just how we do it on WhatsApp. Here’s an example. Here, ‘at least’ will be italicised.

My high school grammar class tells me, there are _at least_ three errors in the quoted text.

If you use Markdown Writer, highlight the text you’d like italicised, and press Ctrl + I.

Other important entities

All our content is HTML. When putting up content, especially since we’re all about literature, a style guide is important. It shows that we care about quality.

Open Live Writer used to take care of those little things like an em-dash and all, when you typed. It wouldn’t be the case here. We need to take a small step to ensure things are as we need them to be. It’s absolutely possible, no worries.

Please follow the guidelines listed below to ensure we maintain our reputation with respect to quality:

  1. Use hyphens to spell multipart words, such as, “hither-thither”. Use a hyphen with phrasal adjectives as well, such as “high-end machinery”. Writing a hyphen is as simple as typing the - key on the keyboard.
  2. Use an en-dash to show ranges, or when connecting pairs of words, such as “1939–1945”, or “The India–Pakistan relationship”. An en dash is written using a pair of hyphens, like 1939--1945.
  3. Use an em dash to give a nice break to the sentence you’re writing, such as, “Today, book typography is conveniently—and blatantly—ignored.” This is done using three hyphens, like, Today, book typography is conveniently---and blatantly---ignored.
  4. When you want the ellipsis (…), just type three dots ... and Markdown will convert it to an ellipsis character.
  5. Non-breaking spaces are important. These ensure that things like Dr Jekyll and 25 km don’t split—that’s because Dr at the end of a line and Jekyll on the next line would make no sense. You’d need to insert a non-breaking space to ensure this doesn’t happen. Enter a non-breaking space with an HTML entity,  . The ampersand and the semicolon are very important. An example would be, Mr Singh. Also note that a non-breaking space itself is a space, so don’t add an additional space before or after the entity. It’ll simply kill its purpose.

Lists

Our site has to hardly use a list—a bulleted or numbered. However, if we do, here’s how we’d do it:

An example of numbered list would be like this:

1. First point
2. Second point
3. Third point

That's how you make a numbered list.

Notice the blank lines before and after the list. It is important. The list would not be rendered properly if the blank line is ignored.

If you use Markdown Writer, type 1. First point; the moment you hit Enter, 2. would’ve been automatically added for you. Press Enter at the end of a blank point to come out of the numbered list mode.

An example of bulleted list would be like this:

* First point
* Second point
* Third point

You could also use a hyphen, like so:

- First point
- Second point
  - A subpoint
  - Another subpoint
- Third point

Hit the Tab key on your keyboard for indentation. You could also add a couple of spaces before the hyphen for indentation. Markdown can understand that.

Same goes for Markdown Writer; you can type a hyphen or a star and write the point text, then hit Enter to get the bullet automatically added for the next point.

Hyperlinks are simple. Enclose the text to show on the page in square brackets, [like so], and enter the link in parentheses, like Visit [Meraki Post](www.merakipost.com) for more exciting content!, to get “Visit Meraki Post for more exciting content!”

Pushing content to GitHub

Ensure that you’ve updated Atom. The version of Atom should be v1.18.0 or higher. To check and/or update Atom, go to Help > About Atom in the Atom editor. Atom 1.18.0 brings GitHub integration that would ease out a lot of our tasks. There would be no need to switch to the GitHub app to push content to GitHub.

  1. The first thing for you to do is pull contents from the site. This is because many of us may have made changes to the files since your last push.
  2. Create/edit the file you’d like to create or edit.
  3. After you’re done adding/editing the content, save the files you changed.
  4. Look for x files at the bottom-right of the Atom window—this is the change count indicator that tells you how many files you’ve changed. Click on it.
  5. A pane would pop in from the right. Click on Stage all. Your files should move to the sub-pane below, called Staged Changes.
  6. Enter a to-the-point commit message. It should tell us why you made the commit. An example would be, Edit the How to Kill a Mockingbird post. Commit messages are usually in simple present tense.
  7. The file count indicator would show 0 files. Right next to it, to the left, you should see a button like ↓↑. Click on it and in the small button pop-out, click on Push.
  8. Wait until the sync completes. The sync animation disappears in case of a successful push. The numbers next to the arrows button also vanish.

Supercharge your writing

One-time setup

Download markdown-writer for Atom. Our GitHub project has some customization done, to bring in some level of automation.

The shortcuts

To create a new post, press the Alt key and from the menu on top, select Packages > Markdown Writer > File > New post. (Or if you like keyboard shortcuts, press Ctrl + Alt + P.) Fill in the name and the date you’d like the post published on, and a good chunk of the boring task of filling the frontmatter is already done!

It will:

  • Automatically create a post in the _posts directory.
  • Show the mandatory frontmatter form, which you can fill.
  • Generate some of the content, such as the date and the slug.

To add emphasis, or toggle heading style and all, refer the keybinding cheatsheet below. Select the text you want to apply formatting to, and hit the relevant combination:

Shortcut combination
Result
shift-ctrl-K Insert link
shift-ctrl-I Insert image
ctrl-i Toggle italic text
ctrl-b Toggle bold text
ctrl-h Toggle strikethrough text
ctrl-1 Toggle H1
ctrl-2 Toggle H2
ctrl-3 Toggle H3
ctrl-4 Toggle H4
ctrl-5 Toggle H5

This is not an exhaustive guide, but a good starting point. If you need assistance, you know where to find Ram!