Introduction

Jekyll is a static web site generation tool. I use it for this web site and it works great. Jekyll not only generates the content from plain text files making editing of content easy to do. Jekyll also serves them for reviewing and editing format.

Jekyll uses a Markdown plug-in to generate the web pages from plain text files. It allows editing of content in a simple and familiar text editor. Markdown syntax is processed by default using kramdown and there is a good reference for it here or here.

There are additional steps in processing the pages. It is important to have a basic understanding of YAML for frontmatter in pages. Using YAML and frontmatter is not too difficult.

Jekyll also uses the Liquid template language. This is a little more complicated but still not too difficult.

The final part of formatting static pages is CSS. I think CSS can be the most complicated part of the system and understanding which files to change and how to get the CSS in a specific location is not very easy. However, once you understand in which file changes are applied in and how to get the settings to display in your page it is just a matter of repeating those steps. I plan to have another post to talk about CSS and SCSS as well as give some examples of how I use it.

For this site, I am using Amazon Web Services S3 to store the static content. Jekyll is more typically used for GitHub pages. I find using S3 very easy and taking advantage of the free tier is great, too. I use a CentOS Linux VM on my Mac for editing, verifying format and publishing. I have the AWS CLI installed so its easy to do the whole process including updating the blog pages on S3.

Start of the Main Section

For the first section the example uses a first level header. Headers start with a # symbol followed by a space and the text for the title. The number of # symbols defines the level of the header. For example, a single one is used to represent Header 1. Two ## represent a Header 2 and so on.

Our example also includes a bookmark that can be referenced in the article to provide a link that moves the article back to this header. The bookmark is indicated by placing it at the end of the header line inside curly brackets. {} This bookmark can be placed in the web page as a link to be used for a reference, table of contents, or simply a way to jump back to the top of the article.

For an example of using a bookmark link, the following link moves to the link examples section. Examples

The primary markup use is:

# Start of the Main Section  {#start}

Use of White Space

With markdown white space is used to define certain parts of a page. For example, it is used to break up text blocks into paragraphs. White space is an important aspect of using markdown.

For example, to create a new paragraph in a text block, one simply ends the last line of the paragraph with a return and creates a blank line to separate the next paragraph.

White space can be blank lines, or a specific number of repeating spaces. They all tell the Jekyll plug-ins how to format the text in your document.

List examples

There are two types of lists. Unordered lists and ordered lists. An unordered list is a list of times that all start with bullets. For an ordered list, the items all start with a number or letter and increment between items.

Unordered lists

If you enter a paragraph of text before or after your list, remember that it needs a blank line separating the paragraph from the list. The same is true after the list, there needs to be a blank line to start a new list or paragraph.

  • First item
  • Second item
    • Item a (Use two spaces before the bullet)
    • Item b
  • Third item

This is how the markdown text looks for the above list.

* First item
* Second item
  * Item a (Use two spaces before the bullet)
  * Item b
* Third item

Ordered lists

Ordered list use numbers for each list item. The number you give it doesn’t matter, markdown will increment it for you. In this example all of my list items start with 1..

  1. One
  2. Two
    1. Two item a
    2. Two item b
  3. Three

And a blank line between the next text line.

This is how the markdown text looks for the above list.

1. One
1. Two
   1. Two item a
   1. Two item b
1. Three

It is possible to mix lists and to add paragraph text within a list. See the kramdown reference for more examples.

Now lets try some steps to do something and put more description within the steps. Since this example is steps that are done for a task, we use an ordered list.

  1. First we do this

    Later we have some more description.

  2. Next we do this.

    Then we have more description.

1. First we do this

   Later we have some more description.

1. Next we do this.

   Then we have more description.

Link examples

Hyperlinks are an important part of any web page. Either to navigate easily within a page or to reference other pages. Markdown provides some simple mechanisms to get these links in your document.

The following are some examples followed by the syntax used to make them.

Google main page

[Google main page](https://www.google.com)

Google main page with hover text

[Google main page with hover text](https://www.google.com "Google hover text")

Now we just enter hyperlink in the text with <>.

https://www.google.com

Or link to a header, ids are created automatically. Start

Formatting text blocks

Using pre-formatted text

Quoted text starts with 2 or more spaces

This is pre - f o r m a t t e d text.
It shows just like it was typed.


   This is    pre - f o r m a t t e d  text.  
   It shows just like    it       was typed.

Line breaks and spaces

Normally a line will continue even if it is broken with a return to a new line.

If you want have a line end with a return you should put two spaces
then hit return. The two spaces signal a line break.

To get an extra empty line in the output, put two spaces in that line or use html <br /> break.


Formatting blocks of code

Code examples

For inline use back ticks ` to show code.

Code Blocks use 3 back ticks `.

Optionally you can enter the name of the language you want to format for. The language name is placed after the first set of 3 back ticks that start the code block.

In this example python is used.

With the syntax noted as python:

s = "Python syntax"
print s

Without the syntax noted as python, using default:

s = "Python syntax"
print s

Or can use to show CLI text

$ command output example

alternate version can use 4 spaces to start the line

Formatting tables

Table example: Use vertical bar to separate, start and end are not required. 3 dashes separate the header line. A colon : will right align or center align.

Item Description Price
item1 item1 description 1.00
item2 item2 description 100.00
item3 item3 description 4.00
item4 item4 description 30.00 


| Item | Description | Price |
| --- | --- | --- |
| item1 | item1 description | 1.00 |
| item2 | item2 description | 100.00 |
| item3 | item3 description | 4.00 |
| item4 | item4 description | 30.00 |
{:.mbtablestyle}

Using images

Finally, I will show a simple image example for how to add an image in your text.

Basic example

alt text for this image

The markdown for the image is:

![alt text for this image](/images/In-2C-48px-R.png)

Summary

This article should be enough to work with the default Jekyll setup to publish pages in your blog or web site. There are a lot more things that can be done with Markdown and kramdown.

In a future post I will discuss the cascading stylesheets (CSS) and how to generate them within a Jekyll site. Jekyll uses SASS for generating style sheets. In the Jekyll documentation review the section on assets. I will also discuss using the Liquid template language for adding CSS to a Markdown file.