Web-Dev-2-Notes

Web-Dev-2-Notes

Course notes for WEBD-2008 Web Development 2 hosted on GitHub Pages using Jekyll.

Demo Download

Web Development 2 Course Notes

These Web Development 2 notes were built using the Jekyll static-site generator with the Just the Docs theme.

The published notes are hosted on GitHub Pages here: stungeye.github.io/Web-Dev-2-Notes/

Quick Overview for Other Instructors

  • These notes are written using Markdown syntax and can be edited online.
  • The notes consist of modules written as .md files in the docs folder.
  • The sidebar menu and the module table of contents are auto-generated.
  • Modules can be a single files or can be separated into sub-topics across multiple files.
  • Draft modules can be added that are initially hidden from students.
  • A small amount of custom CSS and Javascript has been added to theme.

Each of these topics is covered below.

Jekyll and Just the Docs

Jekyll is a tool that takes plain text documents and turns them into static HTML websites.

Jekyll sites can be hosted for free on GitHub Pages by going to the repo settings menu and looking for the "Github Pages" section.

The look and feel of a Jekyll generated website can be changed using a Jekyll theme. These notes use the Just the Docs theme. The following sections are provided as a quick start guide, but you should reference the official documentation for the nitty-gritty details on how to work with the theme.

Editing Notes Online

The process for editing the notes online goes as follows:

  • Locate the page you wish to edit on the deployed version of the notes.
  • Scroll to the bottom on the page and click the "Edit this page on Github" link.
  • (This will take you to the correct file to edit in the repo.)
  • Click the edit icon for the module on github. (Pencil icon top right corner above file contents.)
  • Add or change the file contents using Markdown syntax. (See the next section for Markdown details.)
  • Click the green commit button below the web editor to save your changes. (Leave a commit message to explain the intent behind your change/addition.)

If you don't have collaborator access to this remote the above steps should still work, but instead of committing your changes a pull request will be made on the repo.

Writing Notes in Markdown

The notes are written using the Kramdown-variant of Markdown Syntax. This means the notes are stored as plain text in this repository and converted into an HTML website by Jekyll. There is a small amount of meta-data at the top of each markdown file that Jekyll calls front matter.

Markdown allows us to easily add typographic formatting, links, images, and tables to the notes. Everything you need to know about Markdown can be seen at the Kramdown Quick Reference).

Some example Markdown:

# This is a Heading

## And a Sub-Heading

This is a paragraph that includes some **bold** and *italized* text and a [link](http://stungeye.com).

* Item
* List

Which outputs:

This is a Heading

And a Sub-Heading

This is a paragraph that include some bold and italized text and a link.

  • Item
  • List

The File and Folder Structure of the Repository

All of the course note modules can be found in the docs folder as Markdown files with .md file extensions.

The docs folder is structured like this:

- docs
  - javascript
  - other
  - php

If you look in the javascript, other or php folders you will find a sub-folder for each module. These module sub-folders each contain one or more Markdown files along with the module images. The file-system order of theses folders and sub-folders does not affect the other in which modules are listed in the sidebar menu.

Organizing Modules in the Sidebar Menu

The order in which modules are listed in the sidebar menu is controlled using the Jekyll front matter found at the top of each markdown file. The front-matter looks like this:

---
title: Module Title
nav_order: 5
---

The title specified will be the link title used in the sidebar menu. The nav_order controls the order in which modules appear in the sidebar menu.

Adding an Autogenerated Table of Contents to a Module

You can add an auto-generated Table of Contents to any module. This only works well if you break your module into sections and sub-section using level 2 and level 3 headers (created in markdown with two or three hash # marks preceeding your headings).

The code used to add the table of contents is as follows. This should go directly after the front matter:

<!-- prettier-ignore-start -->
# Main Title for Module 
{: .no_toc }

A short introductory paragraph for the module to come before the table of contents.

## Table of Contents
{: .no_toc }

1. TOC
{:toc}

<!-- prettier-ignore-end -->

The generated table of contents will replace the two lines that read 1. TOC and {:toc}.

The {: .no_toc } statement marks headings that shouldn't be included in the table of contents.

The <!-- pettier... --> start and end tags prevents this code from being broken by the Prettier code formatting plugin for VS Code. The blank line above the prettier-ignore-end tag is crucial.

Organizing a Large Module into Sub-Topics

A module can be broken into sub-topic using multiple markdown files in a single module folder. The module sub-topics will be accessible via a sub-menu in the sidebar menu.

To split up a module you need one markdown file to act as the "parent". It will need front matter that looks like:

---
title: Parent Module Title
has_children: true
nav_order: 3
---

Each of the sub-topics or "children" will have front matter that look like:

---
title: Sub-Topic Title
parent: Parent Module Title
nav_order: 1
---

The nav_order for the "children" sub-topics controls the order these sub-topics will show up in the associated nested menu in the sidebar.

I found it helpful to start the parent filename with 00 and then name each child topic starting with 01 and then 02 etc. The file-system order doesn't affect the menu order, only the nav_order can do that, but it's nice to have the file-system order match the sub-menu order.

Adding Draft Modules That Are Initially Hidden From View

Modules with the word "Draft" in their title (as defined in the front-matter) will default to not being shown in the sidebar menu. The visibility of these draft modules can be toggled by clicking on the pi symbol in the footer of the sidebar menu.

This functionality is powered by Javascript code found in the assets/js/mycode.js file.

Customizations Added to the Just the Docs Theme

A few CSS tweaks and utility classes were added to the theme using the _sass/custom/custom.scss stylesheet.

A Javascript lightbox was also added to allow thumbnail images in the notes to be viewed at a high-resolution. See the _includes/head_custom.html file and the assets/js/mycode.js file to see how glightbox was added.

Images are resized to thumbnails using CSS, so large images should be pre-scaled to reasonable sizes. I'd say try to keep images less than 900px wide.

There are three size images thumbnails you can use in the notes:

![Vulnerabilities Make Me Scream](NUCLEAR_DANGER.png){:class="small"}
![Vulnerabilities Make Me Scream](NUCLEAR_DANGER.png){:class="medium"}
![Vulnerabilities Make Me Scream](NUCLEAR_DANGER.png){:class="large"}

Small: 200px height Medium: 300px height Large: 400px height

When clicked these thumbnails will display the full-size image.

You can wrap text around images by making them inline. Inline images will appear to the right of the wrapped text:

![Vulnerabilities Make Me Scream](NUCLEAR_DANGER.png){:class="small inline"}

This is the text that will be displayed to the left of the image.

Editing the Notes Locally with a Live Preview

If you are doing significant editing to the notes it can be nice to do this work on your machine using a text editor like VS Code. It can also be helpful to preview your changes in the browser before committing them to the deployed site. Local editing with an in-browser preview can be accomplished by cloning this repository and setting up Jekyll on your computer.

If you already have Ruby installed on your computer you can install Jekyll and launch the preview server by running the following from a command line within the root folder of the repositor:

bundle install
bundle exec jekyll serve

You can now edit the markdown files in the docs folder directly on your computer using any text editor. The changes you make can be previewed in your browser by visiting the http://localhost:4000/Web-Dev-2-Notes/ preview server.

To push your changes to the deployed notes you will need to use git to add, commit, and push your changes:

git add .
git commit -m "A lovely commit message explaining your changes."
git push origin master
minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog