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 distAny 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
- Prep your tools (install Node.js)
- Make the project (create the Astro site)
- Troubleshooting
- Summary
- Key terms
- Frequently asked questions
- Sources and further reading
Key takeaways
- Install Node.js first.
node -vreturns a version number once it is installed, and the macOS installer also installs npm. npm create astro@latest resume-sitescaffolds the project. This walkthrough chooses the minimal (empty) template, installs dependencies, and initializes a git repository.- Setting
base: '/resume'inastro.config.mjsmakes the site work at/resumeinstead of the main site address. - The Markdown resume lives in
src/dataasresume.mdand is rendered bysrc/pages/index.astrothrough theContentcomponent. npm run devpreviews the site athttp://localhost:4321/resume/, andnpm run buildwrites the static production files todist.
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/bincome 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
.mdfile). - 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 webprojCreate the Astro project with the create-astro command:
npm create astro@latest resume-sitenpx 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?
YesDone 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-site2.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/dataMove 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.md2.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.mjsNew 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.astroDelete 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.astro2.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 buildBuilt! 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.astrodisplays the resume. - Static build
- Pre-generated files produced by
npm run build. Astro writes them to thedistfolder.
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".
