Elvenware

LampMarkdown

Welcome to LampMarkdown

Overview

The goal of this project is to help you move quickly from raw markdown files to a working Apache based web site.

A video associated with this assignment is available here:

To help you understand markdown, try this search:

Step One

You need to get the most recent code from JsObjects. Navigate to your JsObjects directory:

cd ~/Git/JsObjects

Now type git pull.

If you get an error, type the following and try again to pull down the updates:

git stash

Step Two

It is not a good idea to do work in JsObjects. So let's copy the files that I want you to use from JsObjects into another folder. First, create a place in your home folder where you can store programs:

mkdir ~/Source

Now copy the program I want you to use into it:

cp -r ~/Git/JsObjects/JavaScript/NodeCode/MakeHtml/ ~/Source/.

Now set up the program, but don't run it yet:

cd ~/Source/MakeHtml
npm install

There is one last step, which involves installing a program called Jade. You can install it like this:

npm install -g jade

Now just leave that part of the project alone for a bit.

You can expect npm install to issue some warnings or even a few small errors. But if you hit serious errors when you run npm install, try several steps as listed below. The first (jou) should take you to the ~/Git/JsObjects/Utilities directory. From there, navigate into the NodeInstall directory. Some of the install commands might not install anything because the program or programs may already be installed. When running InstallNodePackages, choose e for essentials.

jou
cd NodeInstall/
./NodeInstall.sh
./InstallNodePackages.sh
sudo apt-get install python
sudo apt-get install build-essential
sudo apt autoremove

Install Script

I also have a script called renewMakeHtml, which can help with the install or updating process. This automates the step by step process described above. So if you have already completed the previous section, you need not run renewMakeHtml at this time.

NOTE: I think it is best to go through step by step the first time both so you undrestand what is happening, and also so you can learn how to troubleshoot problems that may occur at each step. However, once you understand the process, the renewMakeHtml script can be useful because it can save time. It is also useful if you need to update MakeHtml because I have changed it. I will tell you if it has changed.

I keep this script in the MakeHtml folder. You don't, however, want to run renewMakeHtml from inside of the ~/Source/MakeHtml folder. I store the file there, just because it belongs to that project, but it should, in our case, be run from ~/Source.

It only needs to be run occasionally. For instance, run it after I have updated my MakeHtml program. (I perhaps should have called it updateMakeHtml, or copyLatestMakeHtml.)

There are only two reasons to run renewMakeHtml:

To install **MakeHtml**
To update **MakeHtml**

The very first time you need to use MakeHtml on a new system, you should copy the script called renewMakeHtml from JsObjects to ~/Source:

cp $JSOBJECTS/JavaScript/NodeCode/MakeHtml/renewMakeHtml ~/Source/.

Then run the script like this:

cd ~/Source
./renewMakeHtml

NOTE: Just to be clear, you would only need to do this in order to install MakeHtml the first time on a new system, or to update MakeHtml if I have made changes to it. If I've made changes I would tell you. It is not something you need to figure out on your own.

But you only need to do this once on any particular system. For instance, once on Pristine Lubuntu at school, once on Pristine Lubuntu at home, and once on EC2. After that you can forget it, unless I specifically say: "Hey, I updated MakeHtml to fix a bug or to get a new feature such as X or Y." Then you would run it to get the latest bits from JsObjects by running the script.

More specifically: after installing MakeHtml, you can use the script to update it. Suppose I have made a change to MakeHtml and wanted you to get my recent changes. Then you should switch to the ~/Source folder, and run renewMakeHtml. That will delete your old copy of ~/Source/MakeHtml and copy out a new one from JsObjects.

The major take away: don't run renewMakeHtml too often. When you run it, the config file gets overwritten, and then you need to edit it again. Only run the script to install the program the first time, or when I announce an update. In the normal course of things, updates are infrequent.

Step Three

Create a new folder in your Documents directory. Name the new folder AllTest:

mkdir ~/Documents/AllTest/

Now use Atom, Remarkable, StackEdit or the editor of your choice to create some markdown files and place them in your new directory. You can use files that you already created, but by the time you are done, you should have at least six markdown files, and at least half of them have to be new: not ones that you used in a previous assignment.

Move at least two of the markdown files into a sub-directory of AllTest. You can call that directory whatever you want. For instance, MoreFiles:

mkdir ~/Documents/AllTest/MoreFiles

Step Four

By this point in the class, you should already have LAMP installed, and have the correct permissions in your /var/www/html folder. But let's make sure it is set up correctly, with bcuser as the owner. Navigate to your /var/www/ directory and issue this command:

sudo chown -R bcuser:bcuser html

note: If the /var/www/html directory is not present, you need to install LAMP. Directions are here:

There is one other little piece that we need to put in place to make this work correctly. On http://www.elvenware.com there is a logo. A picture of mountains silhouetted against the sky. Go to the site, find the logo, right click on it, and save it to your Pictures directory of your home drive.

Now create an images folder for your website:

mkdir /var/www/html/images

Copy your file into that directory, and set the correct permissions so that a user who is not you, who browses to the site, can read it:

cp ~/Pictures/elvenwarelogo.png /var/www/html/images/.
chmod 644 /var/www/html/images/elvenwarelogo.png

When you write 644, you are saying the owner has read and write permissions, while everyone else has only read permissions:

-rw-r--r-- 1 bcuser bcuser 37309 Jan 20 10:49 /var/www/html/images/elvenwarelogo.png

Sadly, there is one last step. In order to get syntax highlighting after our triple backticks in our markdown, we need to include a special CSS file on our website. Here is how to copy it there. Here is what to do:

mkdir -p /var/www/html/css/highlight/
cp ./node_modules/highlight.js/styles/googlecode.css /var/www/html/css/highlight/.

If you are not in the ~/Source/MakeHtml directory, then try this command:

cp ~/Source/MakeHtml/node_modules/highlight.js/styles/googlecode.css /var/www/html/css/highlight/.

Step Five

It is now time to convert your markdown files into HTML and copy them out to your website.

From the ~/Source/MakeHtml directory, issue this command twice:

npm start

Now browse to your website:

There should be at least one link in the file you see. Start clicking, and you should be able to navigate all the files in your site either directly, or through the back button.

NOTE: I reminded you above, but don't forget that you need to run npm install before the first time you run npm start. You usually only need to type npm install one time per project. Once you have issued the command, then the packages that that project relies on have been installed, and you need not issue the install command again. Type npm install one time. After that, you need only type npm start to run the project.

Here is a bit more detail for the technically minded:

When we type npm start, behind the scenes we are running a command that might look something like this: node server.js. This command tells the node compiler to compile and run server.js, where server.js is a JavaScript source file.

Turn it in

Take at least three screen shots of your pages running in the browser.

Issue the following command and take a screen shot of the results:

ls /var/www/html/

Put the contents of your /var/www/html in your repository in a directory called LampMarkdown and push it: :

mkdir ~/Git//LampMarkdown
cp -rv /var/www/html/* ~/Git//LampMarkdown/.

For instance:

cd
mkdir ~/Git/prog270-calvert-2017/LampMarkdown
cp -rv /var/www/html/*.html ~/Git/prog270-calvert-2017/LampMarkdown/.

Put your images in our shared directory on Google Drive in a folder called LampMarkdown, don't wrap them in a zip file. This saves me a step.

Example Images

Your images must be different from these, but they should have much in common with them:

The master list:

Master

The summary:

Summary

A random page:

Typical Files

Hint

Here are some tips and thoughts about this program to help you understand it better.

Summary: The MakeHtml program converts our markdown in the AllTest folder to HTML. It copies the HTML to the /var/www/html folder. MakeHtml is not a service that runs continually. Therefore, each time we update files in the AllTest directory, we need to run (npm start) MakeHtml in order to update the files in /var/www/html. The conversion does not take place automatically, it only happens when we explicitly run the MakeHtml program by typing npm start.

NOTE: In Windows, we typically click on an executable to run it. Here, we are running a program implemented as a NodeJs script. The way to run the script is to type npm start.

Hint

Check ~/Source/MakeHtml/config/ElvenConfig.json to make sure it is compatible with your system. In particular, check the "base-dir", which assumes that your home path is /home/bcuser.

{
  "calvert": {
    "base-dir": "/home/bcuser/",
    "site-dirs": [
      "Documents/AllTest",
      "Documents/AllSite"
    ],
    "destination-dirs": [
      "/var/www/html/",
      "/home/bcuser/temp/test-site/"
    ]
  }
}