Tag: resume website

Recently, I’ve been blessed with time to play around with things I missed in the world of web development while I’ve been heads-down in Android apps. Astro is one of the things I got curious about recently, and my curious mind led me to try making it display a page derived from the contents of a Markdown file containing my resume. Why a resume.md file? Simply because it’s what I happened to have, ready to use at that moment.

So, how do we serve an Astro Site from Subpath like /resume?

Quick answer for TL;DR peeps :-p

Tested: November 8, 2026 on macOS with Node.js v26.13.0 and Astro v7.4.7:

To build a resume website with Astro, install Node.js, create a project with npm create astro@latest resume-site (minimal template), save your Markdown resume as src/data/resume.md, set base: '/resume' in astro.config.mjs, render the resume in src/pages/index.astro, preview it with npm run dev, and generate the static files with npm run build. The result is a single-page static site served from the /resume path (locally at http://localhost:4321/resume/) that displays your Markdown resume.

To dive into more details beyond the above summary, such as screenshots from my terminal, copy-pasted code from files I edited, a troubleshooting “cheatsheet” table, and an FAQ.

Everything below was run on a Mac, and the exact versions are listed in the “Tested with” table for our reference. Yes, “our reference” — I write these how-to articles mainly for myself because I tend to easily forget things. (That girl could never remember if a friend resides in Pampanga or in Pangasinan? I’d rather not name that girl, but let’s call her Catzie.)

Okay, back to serious business!

Every command relevant to this article, in one place:

node -v
cd Documents
mkdir webproj
cd webproj
npm create astro@latest resume-site
cd resume-site
mkdir src/data
mv /path/to/myresume.md src/data/resume.md
vim astro.config.mjs        # set base: '/resume'
vim src/pages/index.astro   # render the resume
npm run dev                 # preview at http://localhost:4321/resume/
npm run build               # static files are written to dist

Any text editor works in place of vim. It’s just been a long-time habit of mine to use vim when I edit text files quickly through command line interface. The exact contents of the two edited files are in steps 2.2 and 2.3 below.

In this article

1. Prep your tools (install Node.js)
2. Make the project (create the Astro site)
   1. Add your resume file to src/data
   2. Set the base path in astro.config.mjs
   3. Create index.astro to render your resume
   4. Test locally with npm run dev
   5. Build the real files with npm run build
3. Troubleshooting
4. Summary
5. Key terms
6. Frequently asked questions
7. Sources and further reading

Key takeaways

• Install Node.js first. node -v returns a version number once it is installed, and the macOS installer also installs npm.
• npm create astro@latest resume-site scaffolds the project. This walkthrough chooses the minimal (empty) template, installs dependencies, and initializes a git repository.
• Setting base: '/resume' in astro.config.mjs makes the site work at /resume instead of the main site address.
• The Markdown resume lives in src/data as resume.md and is rendered by src/pages/index.astro through the Content component.
• npm run dev previews the site at http://localhost:4321/resume/, and npm run build writes the static production files to dist.

Tested with

Component	Version or detail
Node.js	v26.13.0 (64-bit macOS installer from the LTS page)
npm	v11.20.0
create-astro	5.3.1
Astro	v7.4.7 (shown in the dev server output)
Starter template	Minimal (empty)
Operating system	macOS
Date tested	November 8, 2026

Prerequisites

• A Mac with a terminal. This walkthrough uses macOS, and paths such as /usr/local/bin come from the macOS installer.
• Node.js, which you can get from the Node.js download page. Astro’s dev environment setup guide currently lists v22.12.0 as the minimum supported version and says odd-numbered versions are not supported (checked November 2026). This article uses v26.13.0.
• A resume written in Markdown (a .md file).
• A text editor. This article edits files with vim in the terminal, and includes the few vim keys you need.

Part 1: Prep your tools (install Node.js)

This part checks whether Node.js is already installed and, if it is not, installs it on macOS. Node.js and npm are needed for every Astro command used later.

I ran node -v in my terminal and it returned “not found”, so I installed Node.js on my Mac with the details below.

I downloaded the 64-bit installer from the LTS page (at the time it was https://nodejs.org/en/blog/release/v26.13.0).

The 64-bit installer package installed the following:

• Node.js v26.13.0 to /usr/local/bin/node
• npm v11.20.0 to /usr/local/bin/npm

My Mac then asked whether I wanted to move the “node js” installer to the trash, and I said yes!

I closed and reopened the terminal, and node -v now returns v26.13.0. Sweet.

Part 2: Make the project (create the Astro site)

This part scaffolds a new Astro project named resume-site with the create-astro command and the minimal (empty) template, then adds the resume file, sets the base path, creates the index page, tests locally, and builds the static files.

Create a webproj folder in Documents and move into it:

cd Documents
mkdir webproj
cd webproj

Create the Astro project with the create-astro command:

npm create astro@latest resume-site

npx asks to install [email protected], and I answered y:

Need to install the following packages:
[email protected]
Ok to proceed? (y) y

> npx
> 'create-astro' resume-site

Answer the questions that create-astro asks. Use the arrow keys to choose an option, then press Enter.

My answers:

tmpl   How would you like to start your new project?
       Use minimal (empty) template

deps   Install dependencies?
       Yes

git    Initialize a new git repository?
       Yes

Done for now. Here is the finished setup:

Omg, it created the initial commit for me. Saved mental resources, such as what to write as the commit message:

git log
commit 30521bd903ee79f2b87b4df4cb07a8a0cd417832 (HEAD -> main)
Author: houston[bot] <[email protected]>
Date:   Sun Nov 8 17:21:25 2026 +0800

    "Initial commit from Astro"

Move into the new project folder. Every remaining command in this guide runs from here:

cd resume-site

2.1 Add your resume file to src/data

Create a src/data folder inside the project and move your Markdown resume into it as resume.md so the index page can import it.

Create the data folder inside src:

mkdir src/data

Move your resume file into [...]/webproj/resume-site/src/data. Rename it to resume.md while moving it, because index.astro imports ../data/resume.md:

mv /path/to/myresume.md src/data/resume.md

2.2 Set the base path in astro.config.mjs

Replace the contents of astro.config.mjs with a configuration that sets Astro’s base option to /resume, so the site is served from the /resume path.

Open the Astro config file in vim:

vim astro.config.mjs

New to vim? You only need these keys. Type gg then dG to delete everything in the file. Press i to start typing, paste the code, press Esc, then type :wq and press Enter to save and quit. Any other editor works too.

Delete everything in the file. Paste this:

import { defineConfig } from 'astro/config';

export default defineConfig({
  base: '/resume',
});

Save the file.

This is the most important step. It makes the page work at /resume instead of the main site address.

2.3 Create index.astro to render your resume

Replace the contents of src/pages/index.astro with a page that imports Content from the Markdown file and renders it.

Open index.astro in vim from the project folder:

vim src/pages/index.astro

Delete everything in it (same vim keys as above). Paste this:

---
import { Content } from '../data/resume.md';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Art Resume</title>
  </head>
  <body>
    <main>
      <Content />
    </main>
  </body>
</html>

<style is:global>
  body {
    max-width: 42rem;
    margin: 2rem auto;
    padding: 0 1rem;
    font-family: system-ui, sans-serif;
    line-height: 1.7;
    font-size: 1.1rem;
  }
</style>

What this does: the block between the --- lines imports Content from your Markdown file, <Content /> renders that file as HTML inside <main>, and the <style> block centers the text in a readable 42rem column. Change the <title> to whatever you want shown in the browser tab.

Save the file. Your project now contains these files (other generated files omitted):

resume-site/
├── astro.config.mjs
├── package.json
└── src/
    ├── data/
    │   └── resume.md
    └── pages/
        └── index.astro

2.4 Test locally with npm run dev

Start the Astro dev server with npm run dev and open the /resume path on localhost port 4321 to preview the page.

Run npm run dev inside the resume-site folder:

npm run dev

It runs and displays the Markdown content as expected on http://localhost:4321/resume/. Because base is set to /resume, open that path rather than the plain http://localhost:4321/ address.

Press Ctrl+C in the terminal to stop the server.

2.5 Build the real files with npm run build

Run npm run build to generate the static production files, which Astro writes to the dist folder.

Run the build command:

npm run build

Built! Here is the build output:

Because base is /resume, the files in dist should be served from the /resume path on your site.

Troubleshooting

These are the problems most likely to come up in the steps above, based on how each step works.

Symptom	Likely cause	Fix
node -v says “not found”	Node.js is not installed, or the terminal was opened before the install finished.	Install Node.js from the download page, close and reopen the terminal, then run node -v again.
Astro commands fail on an old Node.js	Your Node.js is older than Astro’s minimum, or is an odd-numbered version.	Run node -v and compare it with the minimum listed in Astro’s setup guide (v22.12.0 when checked in November 2026).
http://localhost:4321/ does not show your resume	base is set to /resume, so the page lives under that path.	Open http://localhost:4321/resume/ instead.
An error about ../data/resume.md not being found	The resume file is missing from src/data or has a different name.	Make sure the file is exactly src/data/resume.md, or change the import path in index.astro to match your file name.

Summary

You now have an Astro project named resume-site that renders a Markdown resume at /resume. It was previewed locally at http://localhost:4321/resume/ and compiled to static files with npm run build. Because base is set to /resume, the page is served at the /resume path instead of the main site address.

Catzie’s Qualms re using Astro specifically for a one-page resume site

The site I created was just a resume with 1 page. When it was time to add Google Analytics tracking code, it didn’t feel right to open the .astro file again and rebuild just to copy-paste again to my web hosted file. I think if I want to keep Astro as that resume site’s framework, I’d setup a form of CI/CD. Otherwise, I’ll keep it simple with good ol’ HTML + CSS and a dash of JavaScript as needed. At this point, I am not really very familiar with coding in node.js yet! I simply followed other guides to do what I did here. Maybe that’s one thing I’ll try in the near future. 🙏

Key terms

Astro

A web framework for building content-driven websites. This article uses it with the minimal template to generate a static page from a Markdown file.

Node.js

A JavaScript runtime. Astro’s command-line tools run on it, so it must be installed first.

npm

The package manager installed alongside Node.js. It runs the create, dev, and build commands in this article.

Base path

The URL subpath a site is served from. With base set to /resume, Astro uses that path as the root for pages and assets in development and in the production build.

Content component

A component Astro makes available when you import from a Markdown file. It renders the file’s full body as HTML, which is how index.astro displays the resume.

Static build

Pre-generated files produced by npm run build. Astro writes them to the dist folder.

Frequently asked questions

How do I check whether Node.js is installed on a Mac?

Run node -v in the terminal. A version number such as v26.13.0 means Node.js is installed. A “not found” message means it still needs to be installed, which is what happened at the start of this walkthrough.

Which Node.js version does Astro need?

Astro’s dev environment setup guide lists v22.12.0 as the minimum supported version and says odd-numbered versions are not supported (checked November 2026). This walkthrough used v26.13.0.

What does the base option in astro.config.mjs do?

The base option sets the path the site is served from. With base: '/resume', the page works at /resume instead of the main site address, and the dev server URL becomes http://localhost:4321/resume. Astro’s configuration reference describes it as the base path to deploy to, used as the root for pages and assets in both development and the production build.

Which Astro starter template does this tutorial use?

It uses the minimal (empty) template, answers Yes to installing dependencies, and answers Yes to initializing a git repository. The contents of src/pages/index.astro are then replaced with a page that renders the Markdown resume.

How does the index page display a Markdown resume?

The page frontmatter imports Content from ../data/resume.md, and the page body renders it with a <Content /> component inside a <main> element.

What URL does the Astro dev server use, and how do I stop it?

In this walkthrough, npm run dev started the dev server at http://localhost:4321/resume. Press Ctrl+C in the terminal to stop it.

Why doesn’t http://localhost:4321/ show my resume?

Because base is set to /resume, the resume page lives under that path. Open http://localhost:4321/resume/ instead of the plain localhost address.

What does npm run build produce?

It generates the static production files. In the build output in this article, Astro reports a static output, builds one page, and writes the files to the dist folder inside the project.

Where do I put the built files so the resume works at /resume?

Serve the files from the dist folder at the /resume path on your site. Because base is set to /resume, the built page expects to be reachable there rather than at the main site address.

How do I edit files in vim if I have never used it?

Open the file with vim filename. Type gg then dG to delete all existing lines, press i to start typing, paste your code, press Esc, then type :wq and press Enter to save and quit. Any text editor works as well.

Does create-astro create a git commit automatically?

When you answer Yes to initializing a git repository, the project starts with an initial commit. In this walkthrough, git log showed a commit authored by houston[bot] with the message "Initial commit from Astro".

Sources and further reading

• Astro configuration reference: the base option
• Astro tutorial: prepare your dev environment (Node.js requirements)
• Markdown in Astro: importing Markdown and the Content component
• Node.js downloads