learning how to make a website

I’ve been eyeing Astro for a while as a modern content-based static site creation tool, so decided to use HTMAA as an excuse to try it out!

It seems appealing to me because:

• It’s lightweight and highly customisable
• It’ll allow me to write pages in Markdown, which just seems much more friendly for blogging and documentation - a habit I’m bad enough at keeping up already.

Creating the Site

To get me started, I followed the tutorial on https://docs.astro.build/en/tutorial.

Hooking it up to HTMAA website

Where to put the built webpages?

After my first commit, the first issue I realised was that my index.html was not the index.html in my home folder, but rather down the file chain at /astro/dist/index.html. A simple solution to this would be to just move all my files from /astro/dist/ to the root.

(mv is annoying about overwriting folders, so the command I’m actually using cp -r astro/dist/* . with astro/dist in my .gitignore. this should probably be automated at some point.)

Dealing with URL

Unfortunately, I ran into a bigger issue: the full URL we’re hosted at is actually https://fab.cba.mit.edu/classes/863.25/people/KatherineYan, but all my links with href='/page', for instance, would try to redirect to fab.cba.mit.edu/page - very much not my site. I asked ChatGPT about this with the following prompt:

I'm using astro to build a site and my site's home page is hosted at
domain.com/some/route/to/me/. I'd like my routes e.g. "/about" to go
to  "domain.com/some/route/to/me/about/" but unfortunately with the
way astro builds the site, the routes end up at "domain.com/about",
which doesn't quite work out. How should I fix this?

And ChatGPT directed me to modify the base property in astro.config.mjs. I searched and found this Astro documentation page, and followed the instructions there to fix the link issue.

Duplicated photos?

Already I can see I have the default favicon.svg in two separate places - in . and in ./astro/public. This is probably less than ideal once I start putting in more images, especially given Neil’s attention to file sizes. The solution to this, I think, would be to just not use the folder public? After all, HTMAA already hosts all our files?

So let’s make a files folder like

KatherineYan
├── astro/
├── files/
├── index.html
└── ...

And allow access to files folder when running our dev environment by installing a vite plugin as recommended by this reddit post I found.

This is kind of messy as the plugin copies from /files/ to /astro/dist/files/, which I then copy back to /files/. But as long as it works for now.

MDX files

I wanted to be able to to include images in my .md blog posts, but the route issue with the URLs comes up here as well, unfortunately. Furthermore, in a .md file, I can’t just use JS to access the import.meta.env.BASE_URL astro attribute that allows my other links to work. However, I didn’t want to despair of my hope of being able to write in Markdown files just yet.

After some scouring documentation, I found this page that allowed MDX (extended Markdown) integration, with which I could import Astro components. I made an Astro component for images that accessed the BASE-URL and imported that in all my now-.mdx blog posts.