Contributing Content

The EthBuilders' Ethereum Developer Curriculum is completely hosted on GitHub, and open source for anyone to contribute to. However, contributing might seem a bit complex if you don't understand how the repository is structured, and how that structure generates our site at https://ethbuilders.github.io/Curriculum.

To start off, we use a static site generator called Hugo, which essentially ingests our repository and generates all of the html, css, and js required for our site to function (you can check out the generated files at https://github.com/EthBuilders/Curriculum/tree/gh-pages). Contributing content to the website doesn't require knowing about hugo, in fact the only two things you need are some knowledge of markdown and a GitHub account.

tl;dr

To add new content, all you need to do is create a new file or chapter (which is a directory + _index.md file) in whichever directory you want, fill in the required front-matter and content and submit the PR.

**Note: Only chapters can be made in the root of the content directory, otherwise the content won't be rendered on the site. **

Content Structure

All of the content that gets rendered on the Curriculum website, is found in the content directory. This directory is filled with sub-directories (called chapters/sections) and the only files you'll find are markdown files (markdown files have the file extension .md).

Below is a list of the content directory in a tree-like format using the tree command at commit 7298859.

content
├── _index.md				=> https://ethbuilders.github.io/Curriculum/
├── basics
│   ├── _index.md			=> https://ethbuilders.github.io/Curriculum/basics/
│   ├── design_patterns.md		=> https://ethbuilders.github.io/Curriculum/basics/design_patterns/
│   ├── front_end
│   │   └── _index.md			=> https://ethbuilders.github.io/Curriculum/basics/front_end/
│   ├── git
│   │   ├── _index.md			=> https://ethbuilders.github.io/Curriculum/basics/git/
│   │   └── basics.md			=> https://ethbuilders.github.io/Curriculum/basics/git/basics/
│   ├── open_source.md			=> https://ethbuilders.github.io/Curriculum/basics/open_source/
│   └── support.md			=> https://ethbuilders.github.io/Curriculum/basics/support/
├── finance_and_economics
│   └── _index.md			=> https://ethbuilders.github.io/Curriculum/finance_and_economics/
├── glossary
│   └── _index.md			=> https://ethbuilders.github.io/Curriculum/glossary/
├── protocols
│   └── _index.md			=> https://ethbuilders.github.io/Curriculum/protocols/
└── use_ethereum			=> https://ethbuilders.github.io/Curriculum/use_ethereum/
    └── _index.md

7 directories, 12 files

The URL base is the same for all the rendered pages, https://ethbuilders.github.io/Curriculum. The URL for a specific page is therefore determined by where it is located within the content directory.

For example content/basics/git/basics.md will point to https://ethbuilders.github.io/Curriculum/ + basics/git/basics/ (note that the file extension gets removed and a slash is appended).

You'll also notice that there are a bunch of _index.md files. These aren't substantially different from their sibling markdown files, but they're specifically named _index.md so that hugo (our static site generator) will render a webpage for our directories (chapters/topics). Which leads into the fact that there are two types of pages on our website, chapter pages (which are the _index.md files) and default pages (they're just regular pages within a chapter).

Chapters and Pages

Chapters in our content directory are created by making a subdirectory and putting an _index.md file, and optionally putting additional markdown files and/or more chapters (also created by adding a directory with a _index.md file). This recursive structure allows us to create topics, and divide those topics into sub-topics, and those sub-topics into more sub-topics ad infinitum. There is only 1 requirement when creating chapters and pages, you must include front-matter (which is just some meta-data about the document which hugo, our site generator, reads). If your page doesn't have front-matter hugo, will not render the page.

Chapter Front-Matter

For chapter pages, _index.md, you must include the following front-matter at the top of your markdown file.

---
<!-- This is the front-matter and it is required in order for the page to get rendered on the site -->
title: "Basics"  # (required) the title of the page
date: 2020-12-27T23:24:30-05:00  # (optional) the date the page was first created  
weight: 1  # (required) the position of the page in the left nav-bar relative to sibling pages/chapters on the same level
chapter: true  # (required) a boolean value denoting whether the page is a chapter
pre: "<b>1. </b>"  # (optional) a string to prepend the title of the page in the left nav-bar
---

*Content goes here ...*

Default Front-Matter

For default pages, it's best that you name the file close to the topic, and include underscores to separate words. The following is the front-matter required at the top of your markdown file

---
<!-- This is the front-matter and it is required in order for the page to get rendered on the site -->
title: "Design Patterns"  # (required) the title of the page
date: 2020-12-28T00:52:03-05:00  # (optional) the date the page was first created
draft: false  # (required) boolean denoting whether the page is a draft (if this is true it will not appear on the site)
weight: 3  # (required) the position of the page in the left nav-bar relative to sibling pages/chapters on the same level
---

*Content goes here ...*