μJam – Documentation

Installation #

This is an installation guide for μJam, an extension to Visual Studio Code. VS Code is a powerful and heavily used open source editor from Microsoft available on Linux, Mac and Windows platforms. The most important feature in this context of website creation and authoring is VS Code being a highly sophisticated Markdown Editor.

So in using this installation guide we need only few prerequisites.

Fig. 0: Alternative way to install μJam directly from inside VSCode.

You may like to hear that ...

We will do that in three simple steps:

  1. A New Project
  2. Generating Content
  3. Publish to the World

A New Project #

For a new project we need a project folder, where everything necessary can reside in. For creating that new folder

  1. Open a new terminal session right in vscode editor.
Fig. 1: Start with a blank editor and open a new terminal session.
  1. Type in the terminal window the command mkdir (make directory) and ...
    specify with it the path to our new project folder first.
> mkdir <new folder path>

Important !
For simplicity reasons the root directory '/' is taken here as the location of the project folder. This should be avoided in general and is even restricted under Unix / OSX. Take your /home directory instead (> cd ~).

md = make directory
Fig. 2: Create a project folder.
  1. We navigate to our newly created folder via cd (change directory) and create there another directory docs.
> cd first
> mkdir docs
Fig. 3: Navigate to project folder / create new directory 'docs'.

We want to create the first file in our nearly empty directory first.

  1. Select in the menu File > New File (Ctrl + N).
  2. Copy and paste the following text into its window (Ctrl + C, Ctrl + V).
{
  "name": "first",
  "description": "My first web page using microjam",
  "version": "0.1.0",
  "author": "it's me",
  "microjam": {}
}
  1. Save the file via File > Save As... (Ctrl + Shift + S) giving it the name package.json. Save it into the new project directory first.
Fig. 4: Create the 'package.json' file.

With that we finished our first step in creating a new project and will proceed in generating some content.

Generating Content #

We now start to write some Markdown documents using vscode as markdown editor.

Information !
μJam basically differentiates between three different types of documents:

  • page represents a stand-alone web page like an about page.
  • articles are web pages building a consecutive list of entries like blog posts.
  • index represents the main page, potentially holding a table of contents of all article pages.

A certain layout is assigned to each of these three types.

At this moment we have a tiny directory structure:

/first
|_ package.json
|_ /docs   (empty folder)

page Document #

Let's create an about page for our first web site.

  1. Copy and paste the following text into a new markdown window (Ctrl + C, Ctrl + V)
---
"layout": "page",
"title": "About"
---

# About this Site 
  
This site was created as a simple collection of markdown files using minimalistic *Static Site Generator* **&mu;Jam**.
  1. Save it to file about.md in the new docs directory (Ctrl + Shift + S).
  2. Show preview window by pressing the red-circled preview-button (Ctrl + K V).
Fig. 5: Writing the 'about' page document.

Explanation !
While working on a markdown file you can always examine the html-result visually side-by-side in a preview window (Fig. 5). Please note some front matter metadata at the top of our about.md file. These metadata are enclosed between two lines of three dashes --- and so separated from the following markdown text. That separator style is taken from yaml, but the metadata itself has to follow json-syntax strictly.

We now want to open our complete project folder in vscode.

Explanation !
After having successfully saved about.md into the docs folder – which is our first content file in this project – we might have realized, that the project directory structure has changed significantly – magically. We want to proof that by vscode's comfortable Explorer View.

  1. Switch on the Explorer View by pressing the uppermost symbol of the Activity Bar, located on the far left-hand side of the editor.
  2. The Explorer View opens and asks us to 'Open Folder'. Pressing this button and selecting our directory /first, we get a nice view of our folder structure (Fig. 6). At the same time the Status Bar color has turned from purple to blue.
  
Fig. 6: Extended project folder structure after saving the first markdown file.

Explanation !

  • In our docs folder two additional files appeared:
    • all generated html-files, which got the filename from their corresponding md-files. So we have here about.html solely.
    • pages.json holding a list of extended metadata extracted from all markdown files. At that time it contains an array literal including metadata of a single page-file now.
  • A new theme folder was created inside of docs. It contains
    • template.json, which holds the default templates for generating html-files from md-files.
    • a single stylesheet file styles.css used by html-files.

If you want to extend this directory structure, add files or modify your templates – maybe you want to add some scripts – you can do this manually at any time from now on. μJam won't touch your folder structure and templates anymore. This was an initial one-time action only.

Now you can view your first web page in the browser of your choice.

  1. Drag 'n drop about.html from the editor's Explorer View (Fig. 6) into the browser's adress bar ... and voilà.
Fig. 7: About page – viewed in browser.

article Document #

We want to maintain a series of article documents, possibly as posts for use with a weblog.

Information !
article documents are not so much different from page documents. In the front matter metadata we need to have a date member. Adding a description member is recommended.

The workflow is illustrated now by the creation of two articles:

  1. Open a new file via File > New File (Ctrl + N).
  2. Copy and paste the following text into that window (Ctrl + C, Ctrl + V)
  3. Save it to file one.md in the docs directory (Ctrl + Shift + S).

one.md

---
"layout": "article",
"title": "Article One",
"description": "This is the first article",
"date": "2020-03-22"
---
### Abstract
This is the first article. We are mainly testing `syntax highlighting` here.

## 1. Syntax highlighting

### 1.1 Html
```html
<!doctype html>
<html>
    <head>
        <title>About</title>
    </head>
    <body>
    <header>header</header>
    <main>
       content here
    </main>
    <footer>footer</footer>
    </body>
</html>
`` `
  1. Open a new file via File > New File (Ctrl + N).
  2. Copy and paste the following text into that window (Ctrl + C, Ctrl + V)
  3. Save it to file two.md in the docs directory (Ctrl + Shift + S).

two.md

---
"layout": "article",
"title": "Article Two",
"description": "This is the second article",
"date": "2020-03-23"
---
### Abstract
This is the second article. Here we are testing math formulas and embedded `svg`.

## 1. Testing

### 1.1 Math Formulas

[Euler's identity](https://en.wikipedia.org/wiki/Euler%27s_identity) is said to be one of the most beautiful formulas, as it collects the most fundamental numbers in mathematics in a compact equation (1).

$$e^{i\pi} + 1 = 0$$ (1)

### 1.2 Vector Graphics

<figure>
<svg width="200" height="100">
   <path d="M100,10L123.5,82.4L61,37.6L138,37.6L76.5,82.4Z"
         stroke="darkslategray" stroke-width="4" fill="orange"/>
</svg>
  <figcaption>Fig. 1: SVG Star</figcaption>
</figure>
Fig. 8: Article document 'two.md'.

Explanation !
While having saved these two *.md documents for the first time, their corresponding *.html documents were created and also their front matter metadata have been extracted, slightly extended and appended to the list of the pages metadata in pages.json. Please note, that μJam will update metadata during consecutive files storages and even remove them together with the *.html files, when you delete a markdown file manually from the file system.

You also might have noticed that we mixed LaTeX math and SVG markup into our markdown text of file two.md (Fig. 8).

index Document #

Let's create the homepage of our website now.

Information !
Any markdown document marked as "index" in its frontmatter layout entry will get appended a list of all articles immediately after its normal content section.

  1. Open a new file via File > New File (Ctrl + N).
  2. Copy and paste the following text into that window (Ctrl + C, Ctrl + V)
  3. Save it to file index.md in the src directory (Ctrl + Shift + S).
---
"layout": "index",
"title": "My Site",
"date": "2020-03-24",
"description": "Homepage of microjam demo site",
"tags": ["microjam","Jamstack","static page","personal",   
         "student","academics","math","vector graphics"],
"category": ["web","math","graphics"]
---

This is a demo site containing some articles. It was made by **μJam**, a minimalistic static site generator.
Fig. 9: Index page.

Explanation !
Since both article documents have abstract sections, that content is used for articles' short description. In case of a missing abstract section, the description entry from frontmatter metadata would have been taken instead.

The content generation process of the demo site is complete now.

Publish to the World #

We want to use well known GitHub here. And we want this version control hosting platform be connected with our local project repository via vscode.

Information !
GitHub as a highly used platform is a code sharing service. But in contrast to mere cloud storage providers GitHub primarily supports project work, where files are regularly edited, uploaded and needed to be managed through version control. This is exactly, what we want to have with our website project and best of all: GitHub provides us with an online repository for free. We then simply have a storage space, called repository, where our project resides on the web. This is not a classical webserver. In the sense of Jam it is a CDN – content delivery network.

The Local Git Repository #

Git is a powerful version control tool, which allows us to create and manage a local repository.

Information !
With it we then have a version control tool Git collaborating with the version control hosting platform GitHub. And Visual Studio Code comes with source control integration and especially has excellent Git support.

Important !
Chances are good that Git is already installed on your local machine. Input '> git --version' at your terminal command line. will show you the current version installed. Otherwise, if you are told that git is unknown, you need to install it. Don't worry, this can be easily done by visiting that download site. I will wait here.

  1. Navigating to the third symbol of the left vertical Activity Bar ... press it.
  2. Press the blue button named 'Initialize Repository'.
  3. Type in the commit message 'Initial commit'.
  4. Ctrl + Enter or ...
    • Move the mouse over 'CHANGES' saying Stage All Changes.
    • Press the + sign.
    • Press the check mark.
    
Fig. 10: Initialize local git repository

Explanation !

  • By initializing our local repository we added a hidden directory named .git to our project folder. Fortunately, we don't have to worry about it at all.
  • In the source control view with step 3 we see our 12 files labeled U, which stands for untracked file.
  • After Stage All Changes in step 4 all files were labeled A then, meaning added to the repository.
  • After step 5 all files vanished from git view, meaning that git took complete control over their versioning from now on. No changes to files can be seen.

To learn more here, I recommend reading 1 [4] and [5].

How helpful git now is for us becomes apparent, when we change the content of ... say one.md and then save the file (Ctrl + S).

Fig. 11: Index page.

Explanation !
The git view shows four files labeled M, meaning modified.

  1. We changed one.md manually.
  2. While saving it, one.html was newly created/overwritten.
  3. pages.json was modified automatically.
  4. Since one.md is an article file, the article list of index.html is potentially affected and file index.html was updated.

Steps 1-3 are always performed under the hood by μJam on markdown file storage.

We can again directly commit these changes now or do that later, while going on and continue to work on other markdown source files.

The Online Repository #

You want to see your pages online now? So you need a personal user GitHub account for proceeding.

Important !
If you do not have a personal user GitHub account, you need to sign up for a new free GitHub account here . Please also note, that you are requested to provide a working email address during verification process.

Now that you are the owner <username> of a GitHub account ...

  1. Navigate your personal browser to https://github.com/<username>.
  2. In the upper-right corner of that GitHub page, use the + drop-down menu, and select New repository.
Fig. 12: Homepage of your GitHub account.
  1. Fill out the formular ...
    • Take a short, memorable <repository name> like 'first'.
    • Description: 'First microjam powered web site' or similar text.
    • Choose public or private.
    • Leave the rest as it is.
    • Press button Create repositiory.
Fig. 13: Formular: Create a new repository.
  1. In a new browser tab/window navigate to https://api.github.com/users/<username> .
  2. Copy your <github user id> from the second line (a series of 6 or more decimal digits) (Ctrl + C) [3].
  3. In the terminal window (on the command line), type:
> git config --global user.name <github user id>
> git remote add origin https://github.com/<username>/<repository name>.git
> git push -u origin master

Explanation !
Please note, that use of these terminal commands is necessary for the first time file transfer to GitHub only. So having done that once, you can forget it forever.

The result of that action on your GitHub account page will be something like this ... (refresh page!)

Fig. 14: Successfully pushed our repository to GitHub.

We will take care about the README in a minute. Now we can't wait to see our website online.

  1. Select settings on your GitHub account page.
  2. Scroll down to GitHub Pages.
  3. In Select source set checkmark at master branch / docs folder.
  4. Navigate to the url shown at 'Your site is published at'.

Fig. 15: Activate GitHub Pages.

Congrats, your first website is online now !