Skip to content

How We Built This Site

This page describes how we built this website and some of the rationale behind why we made various design choices.

Basic Requirements

  1. Hosting the site must be free using GitHub Pages
  2. We need to document the Python sample code
  3. We want professional-quality code highlighting
  4. We wanted the site to have a strong search function
  5. We wanted to make it easy to generate the HTML from easy-to-edit Markdown files
  6. We wanted to make it easy for an instructor to copy the link from any section of any lesson plan directly into a Zoom/Chat window so students can just click on the link to get the right lesson. This is called Deep Linking
  7. We wanted to make it easy to build user interfaces that are consistent with our other projects including:
    1. Beginning Python
    2. Beginning Electronics
    3. MicroPython for Kids
    4. Robot Faces
    5. Clocks and Watches
    6. Robot Day
    7. STEM Robots
    8. MicroSims for Education
    9. Digital Electronics
  8. We wanted to make it easy for other schools and organizations to just "fork" this repository to put their own school logo and colors on the site.
  9. We wanted to leverage existing GitHub tools for reporting bugs, organizing projects and tasks and automating the build process.
  10. We wanted to make sure we would support consistent build and release management so we could add new features without disrupting existing sites. (branches, tagging and release).
  11. We wanted to paste a link on a social media site or a chat like Zoom or Slack and have a nice "Social Media" card to display information about that lesson.

Why Python Mkdocs

The goal of this site is to teach computational thinking in the coolest hands-on way we can think of. We also do this by using AI to help us find the lowest-cost parts.

We also leverage open-source MicroPython, and it is natural to want to use a website builder that also uses Python.
Python is language of data science and AI. So we wanted to create a site that could be familiar to Python developers.

But we also wanted to make it easy for non-programmers to update the site. Let's review some of these design decisions and explain how you can "fork" this site (duplicate it) and put your school or organization's brand and logo on the pages

We will also touch a little bit on how we are using Google Analytics to track site usage and how this can be added with just a few new lines in the configuration file for this site.

Mkdocs vs. Docusaurus

There are two main tools used by Python developers to write documentation: Mkdocs and Docusaurus. Mkdocs is easier to use and more popular than Docusaurus. Docusaurus is also optimized for single-page applications. Mkdocs also has an extensive library of themes and plugins. None of us are experts in JavaScript or React. Based on our ChatGPT Analysis of the Tradeoffs we chose mkdocs for this site management.

GitHub and GitHub Pages

GitHub is a logical choice to store our site source code and documentation. GitHub also has a Custom GitHub Action that does auto-deployment if any files on the site change. We don't currently have this action enabled, but other teams can use this feature if they don't have the ability to do a local build with mkdocs.

GitHub also has Issues, Projects and releases that we can use to manage our bugs and tasks.

The best practice for low-cost websites that have public-only content is GitHub Pages.
Mkdocs has a command (mkdocs gh-deploy) that does deployment directly to GitHub Pages. This was an easy choice to make.

GitHub Clone

If you would like to clone this repository, here are the commands:

1
2
3
mkdir projects
cd projects
git clone https://github.com/dmccreary/microsims

After Changes

After you make local changes you must do the following:

1
2
3
4
5
6
# add the new files to a a local commit transaction
git add FILES
# Execute the a local commit with a message about what and why you are doing the commit
git commit -m "comment"
# Update the central GitHub repository
git push

Material Theme

We had several options when picking a mkdocs theme:

  1. Mkdocs default
  2. Readthedocs
  3. Third-Party Themes See Ranking

The Material Theme had 16K stars. No other theme had over a few hundred. This was also an easy design decision.

One key criterial was the social Open Graph tags so that when our users post a link to a simulation, the image of the simulation is included in the link. Since Material supported this, we used the Material theme. You can see our ChatGPT Design Decision Analysis if you want to check our decision process.

Conda vs VENV

There are two choices for virtual environments. We can use the native Python venv or use Conda. venv is simle but is only designed for pure Python projects. We imagine that this site could use JavaScript and other langauges in the future, so we picked Conda. There is nothing on this microsite that prevents you from using one or the other. See the ChatGPT Analysis Here.

Here is the conda script that we ran to create a new mkdocs environment that also supports the material social imaging libraries.

1
2
3
4
conda deactivate
conda create -n mkdocs python=3
conda activate mkdocs
pip install mkdocs "mkdocs-material[imaging]"

Mkdocs Commands

There are three simple mkdoc commands we use.

Local Build

1
mkdocs build

This builds your website in a folder called site. Use this to test that the mkdocs.yml site is working and does not have any errors.

Run a Local Server

1
mkdocs serve

This runs a server on http://localhost:8000. Use this to test the display formatting locally before you push your code up to the GitHub repo.

1
mkdoc gh-deploy

This pushes everything up to the GitHub Pages site. Note that it does not commit your code to GitHub.

Enable Edit Icon

To enable the Edit icon on all pages, you must add the edit_uri and the content.action.edit under the theme features area.

1
edit_uri: edit/master/docs/

1
2
3
    theme:
        features:
            - content.action.edit

See the Mkdocs Material documentation.

GitHub Action to Deploy After Edit

We want to allow non-technical staff to click the "Edit" button on the pages and just click the "Save". This should trigger the Markdown to HTML conversion and rebuild the site.

GitHub Action for Mkdocs Deply

Mkdocs Material Social Tags

We are using the Material Social tags. This is a work in progress!

Here is what we have learned.

  1. There are extensive image processing libraries that can't be installed with just pip. You will need to run a tool like brew on the Mac to get the libraries installed.
  2. Even after brew installs the libraries, you have to get your environment to find the libraries. The only way I could get that to work was to set up a local UNIX environment variable.

Here is the brew command that I ran:

1
brew install cairo freetype libffi libjpeg libpng zlib

I then had to add the following to my ~/.zshrc file:

1
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

Note that I am running on a Mac with Apple silicon. This means that the image libraries that brew downloads must be specific to the Mac Arm instruction set.