I might have written too much for a intro, you can skip to the next heading
if you are not intrested. :P
Since not long after I got into programming, I have been thinking about making a blog.
I only knew Java then (guess what I used it for).
Later I got to know about JVM family, and learnt Groovy.
Unfortunately other than a build tool of JVM ecosystem, Gradle,
it didn’t make much influence.
I really enjoy its meta programming feature though.
They have some static site generators, but all seems to be knocked together with
various language toolset, python, ruby, etc.
These years I’m more familiar with front-end tech stack. And it makes much more sense to use web technology for web. We have modern frameworks (Vue, React, etc.) and bundlers (rather than task runners). Browsers provides more powerful APIs, javascript standard keeps evolving, and typescript comes to the rescue.
There are a lot of SSG frameworks in front-end, I tends to the ones that are more up-to-date (i.e. which have better integration with Vue, React, …). In the end, I chose Astro as my SSG option. Here I will write some tips along the way as I adding features to the blog.
When creating pages and components
.astro files are static
In Astro, js/ts code in code fences (triple dashes pairs at the top of file),
are executed at build time. It will not run when a user opens your page.
There are only two ways of adding dynamic behaviors, either through <script> tag
and use vanilla js, or using a component from other frameworks.
Page routes have to be generated in advance
In single page apps, a router module typically parses the route params at runtime.
But in Astro, though it has file-based route and route params support (like /pages/[id].astro),
all the possible matches must be generated in advance by defining a getStaticPaths function.
Because all possible routes will corresponding each static html files.
An unmatched route will only result in a 404 page.
Content collections
Usually dynamic routes are used together with Content collections, which are
defined in src/content.config.ts. Define a collection and set a loader and schema,
it will then load all frontmatter properties into the result. You can also pass
a parser function to customize parsing behavior. Then in any astro pages or components,
use getCollection/getEntry to obtain data. (Remember Astro API is only available at build time.)
It’s also how you add features like tags and series.
Some draft for later
- Markdown styling - use tailwind/unocss’s typography preset or your own prefer.
- Add git timestamp like the one in Vitepress’s footer - Vitepress achieved this
by fork and exec git commands. I used
isomorphic-git. - Table of contents and header links - not done yet
- Giscus - not done yet
It takes too much time to write about the blog itself. I might extend these tips further somedays. But for now, I will leave it as is and back to my previous project.