Usbhub

Grace Marcus — Portfolio

Personal portfolio site built with Astro. Static site, deploys to Cloudflare Pages.

Local development

You'll need Node.js v18.17.1 or newer. Check with node -v. If you need to install it, use nvm on Mac/Linux or download from nodejs.org on Windows.

# from the project root
npm install        # install dependencies (only needed first time, or after pulling)
npm run dev        # start dev server at http://localhost:4321

The dev server hot-reloads on save. Open http://localhost:4321 in your browser.

To preview a production build locally:

npm run build      # outputs static site to ./dist
npm run preview    # serves ./dist locally

Project structure

src/
  components/        Reusable Astro components (Nav, Footer, ProjectHero, etc.)
  layouts/           Page wrappers (BaseLayout, ProjectLayout)
  pages/             One file per route
    index.astro      Homepage
    about.astro      About page
    resume.astro     Resume page
    404.astro        404 page
    projects/
      index.astro    Projects index
      [slug].astro   Dynamic route — generates a page per MDX file
  content/
    config.ts        Schema for the projects collection
    projects/        One MDX file per project
      usb-hub-v1.mdx
  styles/
    global.css       Design tokens (CSS variables) and base styles
  config.ts          Site-wide config — name, email, socials, nav links
public/              Static assets — served at the root URL
  robots.txt

Adding a new project

1. Create a new .mdx file in src/content/projects/, e.g. vhdl-system.mdx.
2. Copy the frontmatter from usb-hub-v1.mdx and adjust the values.
3. Use the existing components in the body: <Section>, <HighlightGrid>, <Callout>, <ViewerGrid>, <Viewer>, <SpecTable>, <FilesList>.
4. Save — the page is automatically generated at /projects/<filename-without-extension>/.

Frontmatter reference is in src/content/config.ts.

Updating site-wide info

Single source of truth in src/config.ts:

• Name, email, GitHub, LinkedIn, resume URL
• Nav items
• Site URL (update once you have a custom domain)

Change a value here and it updates everywhere it's used.

Updating colors / fonts

All design tokens live in src/styles/global.css as CSS variables under :root. Change one variable, the whole site updates.

Adding the resume PDF

1. Save your resume as resume.pdf.
2. Drop it into the public/ folder.
3. Delete public/PLACE_RESUME_HERE.txt.
4. The footer and resume page already link to /resume.pdf.

Embedding KiCanvas viewers

Once your KiCad project is pushed to GitHub, replace the placeholder <Viewer> content with the KiCanvas embed tag.

In src/layouts/BaseLayout.astro, add this once inside <head>:

<script type="module" src="https://kicanvas.org/kicanvas/kicanvas.js"></script>

Then in the project's MDX file:

<Viewer label="KiCanvas — Schematic">
  <kicanvas-embed
    src="https://raw.githubusercontent.com/gracemarcus1018-blip/usb-hub/main/usb-hub.kicad_sch"
    controls="full">
  </kicanvas-embed>
</Viewer>

KiCanvas docs: https://kicanvas.org/

Deploying to Cloudflare Pages

One-time setup

1. Push this repo to GitHub.
2. Sign in to Cloudflare (free account).
3. Workers & Pages → Create → Pages → Connect to Git.
4. Authorize Cloudflare to access your GitHub, then select this repo.
5. Configure the build:
   • Framework preset: Astro
   • Build command: npm run build
   • Build output directory: dist
   • Node version: 20 (set under Environment variables as NODE_VERSION = 20)
6. Click Save and Deploy.

Cloudflare gives you a free *.pages.dev URL automatically. Every push to main triggers a new deploy.

Custom domain (optional, recommended later)

In the Pages project settings → Custom domains → Set up a custom domain. Cloudflare walks you through DNS. A .dev domain is about $12/year if you want one — register through Cloudflare itself for the cleanest setup.

Once you have a custom domain, update site in astro.config.mjs and url in src/config.ts.

Build output

npm run build produces a fully static site in dist/. No server, no database. Cloudflare serves the static files from its global edge network.