examples

Examples

The repo of example demos that the introweb.tech website pulls from.

Live at https://introweb.tech/examples.

The repo for introweb.tech/examples (same as the examples.introweb.tech site/repo) can be found here.

Table of Contents

1. How to Read this Repo
   1. _repo-apis
      1. Content API
      2. Zip API
   2. Main Category Directories
   3. root-dir-config.json
   4. General Repo Files
2. How to Contribute
3. Continuous Deployment

How to Read this Repo

Upon first glance there are a few different things you’ll notice in this repo:

• A directory that starts with an underscore (_repo-apis)
• A bunch of category directories (asynchronous, communications, etc)
• A file called root-dir-config.json
• The basic .gitignore, README.md, and continuous-deployment.webp files

We’ll start with _repo-apis

_repo-apis

This directory is where all of the APIs and build scripts live. The APIs are prefixed with api- while the build scripts are prefixed with build-.

Content API

This is the largest API. Started as a mimic of the GitHub API to easily access the code in this repo in a digestible manner, but has grown more features. See full API table below.

Zip API

Designed to return a zip download file of any demo in this repository. User-centered so ignores files irrelevent to the demo (like `quiz.md` and such)

Sidebar Build Process

All of the sidebars for each main category (asynchronous, communications, etc) are pre-generated on build and placed in the top level of each main category in a file called `sidebar.html`. This script creates and updates those files.

Content API

Note: Everything for the Content API is pre-prended with /repos so /:repo/demos becomes https://introweb.tech/repos/examples/demos in practice

Method	Route	Query Params	Returns	Description	Example
GET	/:repo	dir (Optional - the desired subdirectory. Defaults to every subdirectory.)	Object<Array>	All of the file paths for every file (and a URL to reach the file contents at) in the specified repo. In no particular order.	GET /examples?dir=html
GET	/:repo/demos	dir (Optional - the desired subdirectory. Defaults to every subdirectory.)	Array<String>	A list of every demo in the specified repo. In no particular order.	GET /examples/demos?=html
GET	/:repo/demo-frames	none	Array<String>	A list of every demo and what frames they use (e.g. markdown, editor, etc). In no particular order.	GET /examples/demo-frames
GET	/:repo/file/*	none	Object	The contents and metadata of the specified file from the specified repo. Must be a relative route to a file (e.g. `form/spa/index.html`)	GET /examples/file/form/ spa/index.html
GET	/:repo/contents/*	none	String	The direct contents (with the MIME type `text/plain`) of the specified file from the specified repo. Must be a relative route to a file (e.g. `form/spa/index.html`)	GET /examples/contents/ form/spa/index.html
GET	/:repo/contents-mime/*	none	String	The direct contents (with the corresponding MIME type) of the specified file from the specified repo. Must be a relative route to a file (e.g. `form/spa/index.html`)	GET /examples/contents- mime/form/spa/index.html
GET	/:repo/route-configs	dir (Optional - the desired subdirectory. Defaults to every subdirectory.)	Object	Reads all of the demo-config.json and dir-config.json files and makes returns them in a structured object in order according to the configs. If dir is specified, just that subdirectory is returned and all of the demos are flattened (proper order is retained).	GET /examples/route-configs
GET	/:repo/demo-files	none	Object<Object>	Returns an object of every demo containing an array of all of their files.	GET /examples/demo-files

Zip API

Note: Everything for the Zip API is pre-prended with /zip so / becomes https://introweb.tech/zip in practice (the trailing slash having been omitted here)

Method	Route	Query Params	Returns	Description	Example
GET	/	repo & dir (Both required - the desired demo to zip and the repo it's from)	.zip File	Creates a .zip file of all of the relevant files to the specified demo (ignoring files like quiz.md which aren't meant to be seen raw by users).	GET https://introweb.tech/zip?repo=examples&dir=http/bundle-size

Main Category Directories

Outside of _repo-apis, every other folder in the top level of this repo is a “Main Category Directory”. If you look over at https://introweb.tech/examples, the main categories are the sections that say “Part I - Introduction”, “Part II - HTTP”, etc. Everything is built and generated dynamically from this repo, so if a new folder is added, that /examples page will update in the build process.

root-dir-config.json

We’ll talk about dir-config.json files later on, but this root-dir-config.json file is a special file that specifies which order the main category directories should appear in as it defaults to alphabetical.

General Repo Files

• .gitignore has some basics files and direcotries to ignore to keep this repo clean
• README.md and continuous-deployment.webp both make up this current README that you are reading right now.

How to Contribute

Adding a demo

Adding a demo in an existing category / subcategory is pretty straightforward. All of the templates for these files along with the available options for each template will be inside _templates. Follow these steps:

1. Create a new folder next to the other demo(s) in the existing category / subcategory
2. (Optional) If you want this demo to be in a specific order with the other demos it’s near, you can specify that inside the dir-config.json that should be in the same directory as where you just created the new folder.
3. Inside this new folder, create a file named demo-config.json.
4. (Optional) If you want to include markdown to explain your demo, create a file named learn.md to store it all.
5. (Optional) If you want to include a quiz for users to take after going through your demo, create a file named quiz.md.
6. (Optional) If you want to include a tab to store links to resources for users, create a file named resources.md.
7. (Optional) If your demo has media: i. Create a folder inside your demo named media where your media will live. ii. Inside that media folder, create a file named media-config.json. iii. Specify whether you want to use that media inline in the markdown panel or external in its own media panel inside the media config.

Adding a new category / subcategory

Adding a new category / subcategory is also pretty straightforward. All of the templates for these files along with the available options for each template will be inside _templates. Follow these steps:

1. Create a new folder where you want your new category / subcategory to be.
2. Inside that folder, create a file named dir-config.json.
3. If this demo is a main category demo, add its folder’s name to the order array in root-dir-config.json.

Continuous Deployment (CD)

The above diagram illustrates the continuous deployment process of this repository. The process starts on your local machine.

1. On your local machine changes are made to either the examples repo (by adding / modifying a demo) or the examples.introweb.tech repo
2. The git origin is then set to the corresponding bare repository on the DigitalOcean droplet
   • git@introweb.tech:/var/repos/bare/examples.git
   • git@introweb.tech:/var/repos/bare/examples.introweb.tech.git
3. The changes are pushed to the remote machine
4. Both repos have a post-receive hook that then pushes those changes to GitHub and triggers the build process after changes are pushed
   1. The hook first pushes the changes to GitHub
   2. Then, if the changes came from the Examples repo, the hook first runs build-sidebar.js to generate all of the sidebar.html pages
   3. Then the hook removes the old /dist folder from the examples.introweb.tech repo
   4. Finally, the hook initiates the build process for examples.introweb.tech which creates a new /dist folder
5. The examples.introweb.tech DocumentRoot has been set up to live at /var/www/examples.introweb.tech within Apache on the remote server. The actual file at /var/www/examples.introweb.tech is a symbolic link to /var/repos/examples.introweb.tech/dist so creating the new /dist folder automatically deploys the updates live. (This is the dashed green arrow in the diagram)