This repo compiles to the site at https://weteachblockchain.org/ and the progress can be observed from the 'Environments' tab on the Github repo. Be sure to log in as a verified collaborator to see this tab.
To make changes, please checkout a new branch and then create a pull request to the staging branch. Once your pull request is merged to staging, you can preview it here: https://weteachblockchain-org-wine.vercel.app/
- About
- Directory Map
- Local Setup Instructions For Contributors
- Instructions
- Adding Images
- Navigation Header / Menu
- Pages
- Events
- Courses Portal
- CSS / Styles
This site uses the Jekyll templating engine to generate static HTML pages and hosts them using Github pages from the master branch of this repo.
Jekyll uses a combination of Markdown, CSS, and raw HTML to generate pages.
Commits made to the master branch of this repo will trigger a github pages build, which will go live after 2-3 minutes!
If you're not comfortable setting up the repo locally, Click Here for the full instructions to configure VSCode and Github Desktop. The process takes about 15 minutes, and then you'll be ready to start contributing full features!
Main Folder
- _data This directory contains data files which can represent information or provide structure and context.
- _includes This directory contains injectable code components like the navbar and footer.
- _layouts This directory contains the page layout formats
- _posts This directory contains markdown files for blog posts
- _sass This directory contains precompiled scss style code
- assets This directory contains styles and image files
| - css This subdirectory is where the main stylesheets should go
| - img This subdirectory is where images can be added
- node_modules This subdirectory stores node.js modules (mainly bootstrap) DO NOT EDIT
- vendor/ This subdirectory stores ruby vendor files DO NOT EDIT
CNAME This file sets the URL of the github pages build
Gemfile This file contains Ruby Gem configuration information DO NOT EDIT
Gemfile.lock This is a lock file for system specific Ruby build information DO NOT EDIT
package.json This file contains node.js library build information DO NOT EDIT
package-lock.json This file contains system specific node.js library build information DO NOT EDIT
README.md This is the file that creates the docs you're currently reading! EDIT WITH CAUTION
index.html This is the home page
crypto-curious.html This is the CCC landing page
404.md This is the 404 - not found page
< other root pages > Other root pages are also stored in the top level directory and may appear here.
To build the site locally, you must first clone the github repo, and then install the ruby gems and run Jekyll build. Be sure to update your version of ruby to the latest available.
# clone the repo
git clone git@github.com:BlockchainInstituteChi/weteachblockchain.org.git
# enter the directory
cd wtb_staging
# install gems
bundle install
# build jekyll to deploy statically
bundle exec jekyll build
# or serve jekyll locally
bundle exec jekyll serve
** Depending on your Jekyll install, it is possible to skip typing bundle exec and simply type the Jekyll commands.
Jekyll files should all contain a header section (delimited by ---) which details how they will be compiled to HTML. The header can contain a range of information. The header from index.html is shown below as an example.
---
layout: default
title: Home
stylesheet: homepage.css
ogTitle: The Blockchain Institute
ogDesc: We are a nonprofit organization with the mission of educating the world on all things related to blockchain, cryptocurrency, and decentralized technology. Sign up for an in-person class or take a free online course today!
ogImage: https://weteachblockchain.org/assets/img/headerBackgroundTile.jpg
ogUrl: https://weteachblockchain.org/
---
Layouts are a core component of Jekyll and are stored in the folder _layouts. These should not be modified, but a new page can be presented in a different layout by specifying it in the markdown header as shown above.
This is used to set the title as it appears in the browser tab or window. These are not crucial, but will help the user to distinguish tabs. Ideally the title should be less than 20 characters.
Each page should have a personalized stylesheet created and added to assets/css/. The goal of this is to ensure that unnecessary styles are not loaded onto pages where they are not relevant. For some layouts, such as events and lessons, the stylesheets will be predefined throughout the system, so these markdown templates will simply ignore the stylesheet option if it is defined.
The Open Graph Protocol provides social media websites and messaging services with the information that they need to preview a page. These can be set in the header space for any page or post / event and will be displayed automatically when the link is shared!
A full example is shown in the index.html sample above, but this is the general format:
ogTitle: < title to be shown in the preview >
ogDesc: < text blurb to display below the title >
ogImage: < full https:// url to the image to display as a preview >
ogUrl: < the url to display for users >
Images can be added to the folder at assets/img/ and will be automatically served by Github's CDN.
To display an image in a page, use an HTML image tag and a relative path as shown below:
<img src="/assets/img/WTBORG_Events-01.png">
Most of the current layouts use the Navigation header structure to display a menu at the top of the page. This is a slightly complicated functionality, and uses a data file combined with a layout in order to provide a solution which is both customizeable and easy to edit.
The navigation menu is defined in _data/navigation.yaml and can be used to add new items to the header. Each item added should follow this format:
- name: Developer Bootcamp
link: /developer-toolkit/
class: hideOnDesktop
The class should be set to either normal or hideOnDesktop. This specifies whether the item should be shown in the mobile menu only. By default, these will be set to normal and will appear in both mobile and desktop menus.
The navigation menu is built as an _includes component, which allows it to be injected into all pages. The component file can be found at _includes/navigation.html but generally should not be edited.
Pages are the core elements of the site and should be added to the root directory with .html extensions.
Events can be added as markdown files to the directory _collections/_events/. Each file should have the following header.
To create a new event file, copy the template at _collections/_events/.event-template.md to a new file with an appropriate name.
Once published, events will be displayed on the events page at /events/.
Courses have inherited much of their structure from the old Learnpress layout.
A Course has many Modules each of which have one or more Lessons.
To create a course:
- Copy _collections/_courses/.course-template.md to a new file named for the course (i.e. _collections/_courses/courseNameWithoutSpacesOrSpecialCharacters.md).
- Define a course slug (i.e. course-name-without-spaces-or-special-characters) and add it to the header of the course markdown file created in (1.)
- Create an appropriate number of Module files by copying the template at _collections/_modules/.module-template.md and specify the correct course slug (more detailed instructions are in the template file.)
- Create an appropriate number of lesson files specifying the correct module numbers and course slug.
- Save all of the files and wait for github pages to generate them on the live site.
CSS is created from the assets directory and compiles from the _sass directory. Jekyll uses SCSS which is then compiled to standard CSS.
As an example, /assets/css/homepage.css contains the following code:
---
@import "main";
@import "homepageElements";
@import "homepageResponsive";
This means that homepage.css pulls in the sass from _sass/main.scss, _sass/homepageElements.scss, and _sass/homepageResponsive.scss and then compiles them together into the final output css for the page.
In _sass/main.scss it's also important to note that bootstrap and the variables file are imported at the top of the file:
@import "variables";
@import "bootstrap/scss/bootstrap";
The variables file can thus be used to set global constants, for easy updating later. Here's an example of what this looks like:
$white: #fff;
$red: #dc3545;
$body-bg: $white;
$body-color: $white;
/* custom vars */
$custom-font-size: 50px;
These can then be used in other .scss files like so:
.className {
color: $body-color;
}
Bootstrap is a CSS and HTML framework which provides easy to use responsive elements for page design. This streamlines developement for many device types, and ensures consistancy throughout the designs. In order to avoid unnecessary styles being added, please refer to the bootstrap documentation and check for potential solutions before writing custom code.
As noted in the previous section, boostrap is loaded in main.scss, so it should be available on all pages by default. If this does not appear to be the case, please contact Alex and he can troublesheet further.
Because bootstrap is being used for most elements, it is only necessary to make specific tweaks for responsive design. These should generally be stored in a separate css sheet named like xxxxResponsive.scss in the scss/ directory. These can then be imported in the same way that's shown in the SCSS Structure section above.
Responsive css files should follow the structure shown below:
/* Desktop */
@media screen and (max-width: 1000px) {
/* This is for larger devices like iPad Pro */
}
/* Tablet */
@media screen and (max-width: 800px ) {
/* This is for small devices like tablets phones */
}
/* Mobile */
@media screen and (max-width: 600px) {
/* This is for small devices like mobile phones */
}
@media screen and (max-width: 330px) {
/* This is for extra small devices like older iPhones */
}
It is possible to include a variety of items as 'chunks'. These can be used in FAQ and Lesson pages, and can be generated by using the following format:
{% include chunkName.html
param1="value1"
param2="value2"
... etc
%}
- Be sure not to use double quotes (") inside a parameter value. Only single quotes (') are supported.
- All images and file names should be exact matches to a filename from /assets/.
A variety of chunk types are available.
Definitions have a title and a body value. The title should be plain text, but the body supports mixed HTML.
{% include callouts/definition.html
title="HASHING"
bodyText="Creating a unique identifier for a specific piece of data."
%}
Definitions have a title and a body value. The title should be plain text, but the body supports mixed HTML.
{% include callouts/note.html
bodyText="plain text body of the note. Will be prefixed with the word 'NOTE:' in bold."
%}
Definitions have a title and a body value. The title should be plain text, but the body supports mixed HTML.
{% include callouts/callout.html
title="Title"
bodyText="html formatted string for the body of the callout"
%}
Definitions have a title and a body value. The title should be plain text, but the body supports mixed HTML.
{% include callouts/codeSnippet.html
title="The title of the snippet"
bodyText="<span>html formatted string for the body of the callout</span><span>use one span per line of code</span>"
%}
Definitions have a title and a body value. The title should be plain text, but the body supports mixed HTML.
{% include callouts/terminal.html
title="The title of the example"
user="alex@ubuntu"
directory="~/"
bodyText="A list of commands, separated by commas, and including a "
%}
Images with captions can be injected using the following snippet. Images are full width, and support a caption containing a plaintext title (optional) and an HTML or plain text mixed body field.
{% include callouts/imageWithCaption.html
image="Token-Creation-Cycle-01.jpg"
title="The Token Lifecycle"
bodyText="1. Tokens are distributed as rewards when a new block is mined. 2. ... "
%}
A left-aligned image with a text callout can be created using the below snippet.
{% include callouts/imageWithTextCallout.html
title="CryptoKitties"
image="https://theblockchaininstitute.org/wp-content/uploads/2019/02/cryptokitties-200x200.png"
bodyText="A popular collectible dApp released in 2017. Users could bid on digital cats in the form of ERC-721 tokens. This proved to be one of the first “viral” dApps which rapidly gained popularity. As a result, the Ethereum network quickly became overloaded, as it could not process the transactions that were being conducted, resulting in a backlog and very high fees. This incident displayed the limitations of the Ethereum blockchain and showed that the network would have to scale to meet real-world demand."
%}
A gallery grid of images, 4 per row. Clicking on an image enters full screen mode.
{% include callouts/imageGallery.html
title="The title of the gallery"
imageList="courses/bitcoin-for-developers/1_b-01.jpg,courses/bitcoin-for-developers/AliceBobKeys-01.jpg,/courses/bitcoin-for-developers/1_b-01.jpg,headshots/alex.jpg,map.jpg,TheBigPicture-01.jpg"
%}
A twitter feed like the one on the homepage can be included using the following snippet:
{% include socialFooter.html %}
{% include callouts/bigQuote.html
body="Public-key cryptography, or asymmetric cryptography, is a cryptographic system that uses pairs of keys: public keys which may be disseminated widely, and private keys which are known only to the owner. The generation of such keys depends on cryptographic algorithms based on mathematical problems to produce one-way functions. Effective security only requires keeping the private key private; the public key can be openly distributed without compromising security."
sourceName="Wikipedia"
sourceUrl="https://en.wikipedia.org/wiki/Public-key_cryptography"
%}
<div class="topfirstimage" style="background-image: url({% if latest_post.image contains "://" %}{{ latest_post.image }}{% else %} {{site.baseurl}}/{{ latest_post.image}}{% endif %}); height: 200px; background-size: cover; background-repeat: no-repeat;"></div>
Sometimes it is necessary to prevent a segment from breaking across a line break. For example, 501(c)(3) will break on the ( or ) characters, making it less than desirable from an appearance / reader's standpoint. To resolve this, we can wrap the section we don't want to break across a line with a span, like so:
<span class="nowrap">501(c)(3)</span>
This will now be presented ona single line, without breaking!