Digital Design Group  ·  UP EEEi

Contributing a Page

Add or improve content on digital.eee.upd.edu.ph. No experience with the build system required — just edit Markdown files, test with a local preview, and open a pull request. Once it is reviewed and merged, your changes appear on the live site automatically.

Overview

Fork & Clone → Set Up Environment → Edit Pages → Preview Locally → Pull Request

1

Fork & Clone

Get your own copy of the repository.

Fork on GitHub

Click Fork in the upper-right corner of the repository page to create a personal copy under your own account.

Fork on GitHub ↗

Clone to your machine

Replace YOUR_USERNAME with your GitHub username.

git clone https://github.com/YOUR_USERNAME/digital_eee_upd.git
cd digital_eee_upd

2

Set Up Your Local Environment

Three options — all end with a live preview server that auto-reloads on save.

Recommended for most contributors. VS Code detects the devcontainer configuration and sets up the full build environment automatically — no manual installation needed.

1. Install prerequisites
   • Docker Desktop — launch it and confirm the engine is running (whale icon in your taskbar)
   • Visual Studio Code
   • The Dev Containers extension for VS Code
2. Open the cloned folder in VS Code

   code digital_eee_upd

   Or use File → Open Folder and select the cloned directory.

3. Reopen in Container

   VS Code shows a notification in the bottom-right: "Reopen in Container". Click it. If you missed it, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and run Dev Containers: Reopen in Container.

   The first build pulls the container image — this takes a few minutes. Subsequent reopens are instant.

4. Start the preview server

   Open a terminal inside VS Code (Ctrl+`) and run:

   quarto preview

   VS Code will auto-forward the port and offer to open the preview in your browser. The page reloads automatically whenever you save a file.

For terminal users who do not want to use VS Code. Uses the same container image as the devcontainer, so the environment is identical.

1. Install Docker Desktop

   Download Docker Desktop for your OS. Launch it and wait for the Docker engine to be running before continuing.

2. Pull the container image

   docker pull ghcr.io/lawrence-lugs/quartolatex:latest

3. Run a container with the repo mounted

   Run this command from inside the cloned digital_eee_upd directory:

   docker run -it --rm \
     -v "$(pwd):/workspace" \
     -w /workspace \
     -p 4848:4848 \
     ghcr.io/lawrence-lugs/quartolatex:latest bash

   This drops you into a bash shell inside the container with your repo files mounted. Any changes you make on your machine are immediately visible inside the container.

4. Start the preview server inside the container

   quarto preview --port 4848 --host 0.0.0.0

   Open http://localhost:4848 in your browser. The preview reloads automatically on save.

No Docker? Install Quarto and the Python environment directly on your machine.

1. Install Quarto

   Download the installer for your OS from quarto.org/docs/get-started.

2. Install Miniforge

   Miniforge is a lightweight conda distribution that includes the fast mamba package solver. Download from github.com/conda-forge/miniforge.

3. Create and activate the Python environment

   Run these commands from inside the cloned repository directory:

   mamba env create -f .devcontainer/env.yml
   mamba activate numerical_sims

4. Start the preview server

   quarto preview

   Quarto will print the local URL in the terminal output — open it in your browser. The preview reloads automatically on save.

3

Edit or Add a Page

Pages are plain Markdown files. Any text editor works.

What is a .qmd file?

A Quarto Markdown file — just plain Markdown with a short YAML header at the top. Standard Markdown syntax (headings, lists, images, tables, code blocks) all work out of the box. You can also embed raw HTML anywhere for more complex layouts.

Where pages live

Location	Contents
pages/logicLabs/	Logic Labs (lab1.qmd – lab6.qmd and supporting files)
pages/verilogCrashCourse/	Verilog Crash Course chapters
pages/	Standalone pages (e.g. about.qmd)
static_apps/	Self-contained HTML tools (not rendered by Quarto)

Minimal page template

Create a new .qmd file anywhere in the tree. The only required part is the YAML frontmatter at the top:

---
title: "My Page Title"
---

## Section Heading

Write your content using standard Markdown.

![An image caption](images/my-image.png)

The preview server will pick up the new file automatically — no restart needed.

Adding your page to the navbar

If you want your page to appear in the top navigation, add an entry to _quarto.yml under website.navbar.left. If you're not sure how, skip it — maintainers can wire up the navigation during PR review.

4

Open a Pull Request

Push your changes and request a review.

Commit and push your changes

git add .
git commit -m "Add: brief description of your change"
git push origin main

Open the pull request on GitHub

Go to your fork on GitHub. You'll see a banner: "Compare & pull request". Click it, add a short description of what you've changed, then submit.

Open a Pull Request ↗

What happens after merge

The live site at digital.eee.upd.edu.ph tracks the main branch. Once your PR is reviewed and merged, the site rebuilds automatically and your content appears live within minutes.

Questions? Open an issue on GitHub.

View on GitHub