Contribution guidelines

How to write my first tutorial?

Thank you for contributing to this workshop! We are using hugo as a framework to maintain consistency and to automate publishing tutorials to Github.

1. Clone or Fork the repo

Go to eks-workshop repo, on the top-right corner of the page, click Fork

If you are not familiar with Github, follow the instructions mentioned on how to Fork a repo

2. Create new chapter

Each directory within the repo is organized to maintain consistency. For writing new tutorial, you will be focused on /content directory. You want to create new directories for each chapter

From the root of the repo, create new chapter

mkdir content/mynewchapter

Title pages are built from a specific filename called _index.md. Create a new title page for your new chapter

hugo new --kind chapter mynewchapter/_index.md

Let's view the content of this file

$cat content/mynewchapter/_index.md
+++
title = "Mynewchapter"
date = 2018-09-28T18:27:50-04:00
weight = 5
chapter = true
pre = "<b>X. </b>"
+++

### Chapter X

# Some Chapter title

Lorem Ipsum.

We can see the front matter of the page includes a title, weight, chapter set to true by default. The chapter setting enables entry into the ToC. Weight determines the ToC order. At this time, you need to add one more line to this file draft = true. Draft status determines whether or not the page can be published. You can review your changes by running local hugo server.

To see the draft pages, you can run npm run drafts

If you want to see the site without including draft pages use npm run server.

When the site is built and deployed (from any branch), only non-draft pages are included. No drafts are ever published publicly.

3. Create new content

To write new content in your chapter, run

hugo new mynewchapter/thisawesomecontent.md

Let's view this new page

$ cat content/mynewchapter/thisawesomecontent.md 
---
title: "Thisawesomecontent"
date: 2018-09-28T18:29:10-04:00
draft: true
---

You can see that chapter and weight are not set, and draft is set to true. If you want to determine order, add weight to the frontmatter.

Note: The two examples of frontmatter above are in two different formats. These formats are interchangable, but not mixable. If you use any key: value style settings, don't try to mix in key = value. Keep it consistent per page, but changing from one page to the next is acceptable.

Which format do I need to use?

We are strictly using Markdown for tutorials

You might want to take a note of these formatting guidelines as you write your tutorials