Project Portfolio Site¶

Teddy Warner| Summer, 2021 | 6-7 minutes

The behind the scenes of the site you are on right now :)

This site relies on MKdocs, a static site generator is written in python to create the content of the site, as well as the MKdocs Material Theme for customization. I used this same static site generator to create my Fab Academy Documentation Site, however, that site runs strictly on the MKdocs Material Theme without custom alterations. This site relies on the same structure as the prior Fab Academy Documentation Site but includes experiments with entirely custom components, and an altered MKdocs Material Theme. In addition to all that, it’s also built and hosted through my personal GitHub Pages repo, under my personal domain.

Repo Setup and Cloning¶

To start the site I created a new GitHub Pages repo on my GitHub and cloned in some of my site files from my prior Fab Academy Documentation Site (the cloned files were just so site setup files, as well as a bit of content on my Fab Academy final project to be displayed on this site). I then pulled this repo to my local system folder with the command

git clone REPO-HERE # (1)

Replace the text REPO-HERE with your site repo’s Clone with SSH link. This can be found under the Clone button in most Git web interfaces (i.e. Gitlab, Github, etc.).

Do I Need to Clone my Repo Locally?

Modern Hosting Platforms such as GitHub or GitLab allow for Repo editing to take place directly in the browser, and thus technically speaking, one does not need to pull their site Repo locally. However, browser editing eliminates the possibility of locally hosting, and thus one cannot view changes before pushing publically. Despite this, If you’d still like to work in a Browser-based editor, you may skip the SSH Setup and Site Publishing sections, and follow an editing and pushing workflow for your specific browser-based editor.

SSH setup¶

To clone a Git repository locally, an SSH key must be generated on your computer and then attached to your GitHub account. GitHub has really good documentation on creating a new SSH key and attaching it to your Git Web Interface (Github, Gitlab, etc.).

The process for generating and attaching a new SSH key to your Git Web Interface is relatively pain-free when following this documentation and using the command written above. My process involved running these commands …

ssh-keygen -t ed25519 -C "<Your-SSH-Name-Here>" # (1)

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519): # (2)

Enter passphrase (empty for no passphrase): # (3)
Enter the same passphrase again:

cat ~/.ssh/id_ed25519.pub | clip # (4)

This generates a new SSH key on your computer.
Click enter to confirm location.
Enter a passphrase for your SSH key, you will need this password whenever you attempt to push your site.
This copies your new SSH key to clipboard. Replace id_ed25519.pub with your filename. For example, use id_rsa.pub for RSA.

Once copied to the clipboard, you can paste the newly generated SSH key in your SSH key settings in your Git Web Interface, to link your computer and your Git Web Interface. Now you can finally clone your site Repository locally as discussed above.

Mkdocs Material Install & Site Building¶

Requirements

Latest Version of Python Be Sure Your Python Installation is Installed to PATH in the setup wizard
Latest Version of Git

Open your cloned GitHub Pages repo in your code editor of choice, my personal favorite source-code editor is Visual Studio Code, so naturally, I used it. In a new terminal in the clone site folder, run the command

1	`pip install mkdocs-material`

This will install all dependencies needed to run a static site with MKdocs, as well as the MKdocs Material Theme.

Note for Fab Academy Students

The MKdocs Material theme is paired with the mkdocs-git-revision-date-localized-plugin by default in your Fab Academy student repo. This plugin enables displaying the date of the last git modification of a page at the bottom of each page. To build your static site, this plugin must be installed in your local site folder with the line below …

1	`pip3 install mkdocs-git-revision-date-localized-plugin`

However, one may opt to not use it via the removal of the line

- git-revision-date-localized

found under the plugins section of your sites mkdocs.yml file.

Following this setup, I build my static site locally with the command in my site folders terminal

1	`mkdocs serve`

and followed the link given in my computer’s web browser. You should get an output like this after the mkdocs serve command …

INFO     -  Documentation built in X.XX seconds
INFO     -  [XX:XX:XX] Serving on http://YOUR-LOCAL-SITE/

Auto Site Building¶

GitHub Actions

The easiest way for your static site to be built in GitHub pages upon a push is through GitHub Actions allowing for an automated workflow to run to build and pipeline your static site publicly.

At the root of your repository, create a new GitHub Actions workflow, e.g. .github/workflows/ci.yml, and copy and paste the following contents:

name: ci # (1)
on:
  push:
     branches: # (2)
      - master
       - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
          python-version: 3.x
       - run: pip install mkdocs-material # (3)
       - run: mkdocs gh-deploy --force

You can change the name to your liking.
At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.
This is the place to install further MkDocs plugins or Markdown extensions with pip to be used during the build.

For my site setup, I added the line …

- run: pip install mkdocs-git-revision-date-localized-plugin

… to install the Git Revision date plugin to my site, allowing for the date each page was updated to be displayed under all of the contents of the page.

Site Customisation¶

The basic setup and customization of your static site are covered wonderfully on the Mkdocs Material Theme Setup Documentation. However, following this basic theme setup, your site can be altered farther by extending the Material Theme - Witch can be read about here. All of my overrides can be found in this site’s GitHub repo.

Git Pull

When working with other developers in a Git Repo, the Git Pull command is necessary to keep your local branch up to date with others’ work. Running the line …

1	`git pull`

will pull in any pushed changes to your repository, allowing you to merge work/changes with work from other branches.

After working on teddywarner.org for a couple of months, I began to develop a project template page that accumulates different front-end HTML, CSS & Markdown aspects I use on my pages, which can be found via the button below.

Project Page Template

Here I’ve also compiled a bit of a mkdocs markdown cheat sheet with 10 sections for customization, formatting, or additional flair. Again, the Mkdocs Material Theme Setup Documentation covers the theme-specific markdown at length and is a nice resource while setting up specific theme-specific bits. This section compiles theme-specific markdown with overall markdown features & all of the markdowns behind it can be found in the following sections, or on this page source - linked below.

Project Portfolio Site Source Code

1. Markdown Meta Data¶

markdown_extensions:
  - meta

---
title: PROJECT-TITLE
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
template: custom.html
hide:
  - navigation
  - toc
---

2. Basic Syntax¶

Image & CaptionHeadingsHyperlinkBlockquote

![alt text](imageURL.jpg){: align=right/left width="100%"}
  <figcaption>Caption</figcaption>

Terminal output showing successful mkdocs serve command

Caption Example

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

[Hyperlink Example](URl)

Hyperlink Example

> blockquote

Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.

3. Text Formatting¶

markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

Bold Text - **bold text**
Italicized Text - *italicized text*
~~Strikethrough~~ - ~~Strikethrough~~
Subscript - H₂O - H~2~O
Superscript - X² - X^2^

4. Buttons¶

markdown_extensions:
  - attr_list

[Solid Button :fontawesome-solid-download:](URL){ .md-button .md-button--primary}
[Outline Button](URL){ .md-button}

Solid Button Outline Button

5. Different List Styles¶

markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

Unordered ListOrdered ListTask ListDefinition List

“Unordered lists can be written by prefixing a line with a -, * or + list marker, all of which can be used interchangeably. Furthermore, all flavors of lists can be nested inside each other:” ¹

- Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    * Nullam dignissim ultrices urna non auctor.
- Nam vulputate tincidunt fringilla.
    * Nam vulputate tincidunt fringilla.
    * Nullam dignissim ultrices urna non auctor.
- Nullam dignissim ultrices urna non auctor.
    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.

Result -

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
- Nullam dignissim ultrices urna non auctor.
Nam vulputate tincidunt fringilla.
- Nam vulputate tincidunt fringilla.
- Nullam dignissim ultrices urna non auctor.
Nullam dignissim ultrices urna non auctor.
- Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.

“Ordered lists must start with a number immediately followed by a dot. The numbers do not need to be consecutive and can be all set to 1., as they will be re-numbered when rendered:” ²

  1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
      sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
      nulla. Vivamus a pharetra leo.

      1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
          quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
          ultricies libero efficitur sed.

      2.  Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
          rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

          1.  Mauris dictum mi lacus
          2.  Ut sit amet placerat ante
          3.  Suspendisse ac eros arcu

Result -

Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
  1. Mauris dictum mi lacus
  2. Ut sit amet placerat ante
  3. Suspendisse ac eros arcu

- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Result -

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

Result -

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

6. Content Tabs, Code Styling & Annotations¶

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

theme:
  features:
    - content.code.annotate

YAMLC++Python

YAML EXAMPLE
theme:
  features:
    - content.code.annotate # (1)

I’m a code annotation! I can contain code, formatted text, assets/images, … basically anything that can be expressed in Markdown.

C++ EXAMPLE
void setup() {
  pinMode(0, OUTPUT);
}

void loop() {
  digitalWrite(0, HIGH); 
  delay(500);
  digitalWrite(0, LOW); 
  delay(500); 
}

PYTHON EXAMPLE
import tensorflow as tf

7. Footnotes¶

markdown_extensions:
  - footnotes

1
2
3

Here's a sentence with a footnote. [^3]

[^3]: This is the footnote.

Here’s a sentence with a footnote. ³

8. Formatted Tables¶

markdown_extensions:
  - tables

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource