Posts (Overview)
Now that we know what Markdown and Front-matter are, we can begin to look at how posts are written in Assist.
First, let's get an overview of what a post's layout looks like.
Orange Container - Front Matter
Where our Front Matter variables will be declared.
Blue Container - Markdown
Where our Markdown content for the article will be written.
Writing an article in Assist is simple but it still does require a few small details to keep in mind.
How-to articles follow a sequential format. They are a series of steps each with its own explanation and image.
Before writing our article, let’s prep our images.
For each article in Assist there is a folder that contains images for that article. This folder is located inside of the img/ directory within the Assist File Structure and will need to be created by you if you are creating a new post.
NOTE: The name given to each folder containing images will always match the title of the article that those images are for.
There are 2 options when creating a new post: Option 1, where you create it from scratch, and Option 2, where you copy and paste an already made post and modify it.
First write out your front-matter. If you don’t remember what each variable is or what to assign to each variable, you can go ahead and check out the Front Matter tutorial.
After that we start our markdown list. Each list item in our article contains a description for a step followed by an image showing the step. To help visualize this we can look at the following image:
Looks complicated at first, but each how-to article contains this structure. So if you get it down once, you’ll be good to go.
First we define a declare a list item in markdown when we type a number followed by a period. After that we add our descriptive step text followed by a carriage return. You can see in the image above that there is a carriage return symbol. Enabling these invisible characters is explained in the tip below.
Then we add in another carriage return, 4 spaces (in green rectangle), and add our image (orange rectangle).
If you need a refresher for how to create images in markdown, go ahead and follow the explanation here.
NOTE: The text, “{{ site.pathname }}” is a liquid variable. This tells Jekyll to use the site’s pathname which will always be rendered to: https://assist.coe.hawaii.edu/ . What follows is the path to the image itself.
Tip: To help out with editing or writing posts, you may want to check a couple options in your text-editor.
In Atom:
Head to Preferences and check "Show Indent Guide" and "Show Invisibles".
Show Indent Guide will show you indention indicators which will help you out in the long run. Show Invisibles will show your invisible characters such as carriage returns, spaces, etc.
In Sublime Text:
Head to Preferences > Settings - Default. Within the file set draw_white_spacetoallanddraw_indent_guidestotrue`.
This option is simple. Copy an already made post, create a new file, paste the content and modify it.
Tip: It wouldn’t hurt to try Option 1 at least once so that you understand what it is exactly you are modifying when doing Option 2.
NOTE: Make sure you modify whatever needs to be changed, this could be replacing text or images. Also, don’t forget that you will still need to create a folder containing images for this post.