JS411 8-Week Ebook

A dead simple Node Express app that serves static Material Themed docs generated by Mkdocs from behind basic authentication.

For Development

1. Clone this repo
2. Install Node dependencies: npm i (see package.json)
3. Run npm start to see the current state of the ebook.
4. Start with ebook-folder/mkdocs.yml this is the configuration file for this book

Install Python Dependencies

To be able to edit the ebook you will need to follow these steps first:

1. Install Python 3.7+ on to your computer
2. pip should be installed with Python but if not: install pip or pip3 install pip
3. cd ebook-folder to move into the Python package
4. run git clone https://github.com/squidfunk/mkdocs-material.git
5. Install the Python Packages pip3 install -r requirements.txt (See requirements.txt).
6. Run mkdocs build to build the markdown files into static HTML files into the site/ directory.

NOTE1: if you are running Python 2.7 this will not work. You'll need to update to Python 3.7 or higher.

NOTE2: if you are still running into the error your machine may have Python 2.7 set as a default. Change it to an alias so you alwasy use 3.7+ or change to alternative versions.

NOTE3: potential updates needed to Python packages, see requirements.txt. Upgraded pymdown_extensions-8.1.1 to pymdown_extensions-9.4 & mkdocs-1.1.2 to mkdocs-1.3.0 on May 10, 2022. run pip3 install <package> --upgrade

Serve

To serve the files in site/ to port 8000 withOUT username:password authentication simply run mkdocs serve.

To serve with authentication you'll need to add .env file with environment variables to the root directory:

1. cd ..
2. echo "STUDENT_USERNAME=a-username STUDENT_PASSWORD=a-password INSTRUCTOR_USERNAME=a-username INSTRUCTOR_PASSWORD=a-password PORT=5500" >> .env

  STUDENT_USERNAME=a-username
  STUDENT_PASSWORD=a-password
  INSTRUCTOR_USERNAME=a-username
  INSTRUCTOR_PASSWORD=a-password
  PORT=5500

3. From ebook-folder run mkdocs serve
4. From root directory run npm start - to serve files from site/ to port 5500 with username:password authentication

Go to ebook-folder/mkdocs.yml for further instructions + see ebook-folder/workspace for templates and notes.

While working in ebook-folder/ you can simply use mkdocs build and mkdocs serve to by-pass the Node server.

To Deploy

1. Finish your changes and check them with mkdocs serve.
2. Before you git add anything to staging run mkdocs build. This will ensure you've built the newest intended version of the ebook before you push it to GitHub.
3. git status, add, commit, push ... to repo
4. Create pull request & merge

For New Deployments

Heroku will need some environment variables to perform authentication checks. Add them as you would the variables in .env file using he CLI tools or the dashboard.

• ENVIRONMENT : PRODUCTION
• STUDENT_USERNAME : <a-username>
• STUDENT_PASSWORD : <a-password>
• INSTRUCTOR_USERNAME : <a-username>
• INSTRUCTOR_PASSWORD : <a-password>

How to install Python and pip instructions here:

Functional Overview

Mkdocs is a Python package that generates statics web files (HTML, CSS, JS), seen in the site/ directory, from plain Markdown files, seen in the docs/ directory.

Material-Mkdocs is another Python package that builds on top of Mkdocs to provide design from the Material-UI Theme. The two receive their configuration from the mkdocs.yaml file. You'll see the navigation is is provided by the nav: property in that file and the Material Theme is the value of theme:.

The Express server is just an app used to serve the static files from site/ behind basic authentication thus the Node app is deployed and not the Python code.