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. Follow eks-workshop repo to install hugo, npm and other setup instructions

3. Create new chapter

Each directory within the repo is organized to maintain consistency. For writing new tutorial, you will be focused on /content directory (read below for uploading images). 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. You can review your changes by running local hugo server.

You can run npm run server to see the changes locally

4. 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. Draft status determines whether or not the page can be published. 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. We recommend to send the PR with draft: false as it helps with review process

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

Where to upload Images?

Images can be uploaded to /static/images directory. Here is an example for linking an image using markdown syntax

![alt text](images/imagefilename.svg)

We prefer SVG for any diagrams, or original artwork. If SVG isn't available, then PNG, followed by JPG/GIF

Try to include largest image possible. We dynamically resize downward, but not up.