The response I’ve received to my recent posts about the Astro static site generator (SSG) suggests there are a lot of you out there considering moving your own websites to it. While I already gave my thoughts about how Astro compares to the other SSGs with which I have experience, I figured you’d also find it useful if I gave you some tips about the sorts of changes you’d face in such a move. I am speaking here mainly about moving from a site that’s currently on either Eleventy or Hugo, although you likely can adapt this information to the migration of a site built with another SSG.
Modifying your Markdown
One of the first and most obvious challenges you’ll face in an [x]-to-Astro move is how you must change your site’s Markdown files when you bring them over.
The setup item
At the top of each file’s front matter, you’ll have to add a setup item with one or more entries.1 For example, here’s how it could look for the post you’re reading now:
---
setup: |
import Layout from '@layouts/Post.astro'
import Box from '@components/Box.astro'I created the Box component for, say, an item2 like this:
Note: This box calls your attention to this item.
. . . called as follows:
<Box>
**Note**: This box calls your attention to this item.
</Box>Shortcodes to components
If you’ve used shortcodes in Eleventy or Hugo to inject items into Markdown, you’ll need to convert them to Astro components which you then will import into the Markdown, as shown in the second code block above with the Box component.
Probably the best example I can give you from my own experience is my static tweets shortcode, which I turned into an Astro component. I have yet to find a shortcode that couldn’t be “component-ized.” If I can do it, so can you.
Change isn’t always a constant
The good news is that there are plenty of things in your existing Markdown you won’t have to change:
- In general, Markdown still functions as always.
**This should be bold**results in a bold-faced “This should be bold,”#makes a line anh1, and so on. - You can keep the front matter’s existing
dateor other self-specified metadata (such aslastmod, which I use to indicate when I last modified a file after its initial publication). In short, correct YAML won’t cause a problem. (On the other hand, FUBARed YAML causes a problem in just about any SSG.) - You can still specify
draft: true, as in Hugo by default and Eleventy through fairly simple configuration, to prevent a file from being built when it’s not ready for publication. This is especially helpful if you have to commit the file to the site’s public repository, such as when you’re using multiple devices to handle the file, before you want it to be “live” for the world.
DX suffers on larger sites
If your current site has only a few pages, you’ll find Astro’s dev server refreshes the browser quickly enough to suit you. However, after your content gets up to and beyond about the 100-page level, even a fairly simple content edit will cause the refresh to take several seconds when you save the file you’re changing, and the lag will get longer as the site gets bigger.3
The Astro devs are aware of the issue — perhaps related to Astro’s interaction with Vite — but it’s unknown when it’ll be fixed. Thus, with a larger site, you may want to get used to writing your content outside of development mode and, only then, activating the Astro dev server to check the new page’s appearance.
It’s still beta, remember
One critical thing to remember is that there still are a few weeks to go before the planned release to GA of Astro v.1.0; so, until then, Astro remains in beta and you should assume there will be glitches, fixes, changes, hurried documentation revisions, and the other items that typically accompany that status.
Speaking of which . . .
A sheepish U-turn
Forgive me for burying the proverbial lede but, today, two weeks after moving this site from Hugo to Astro, I moved it back — at least for the time being.
I reluctantly made this choice after running into a few particular Astro glitches which turned out to be more limiting, and required more sweating over workarounds with which I’m only slightly familiar, than I’d anticipated. (There also were some external, non-Astro-related factors which played a significant role in tipping my hand, but they’re not really germane to this discussion.)
This setback notwithstanding, I remain optimistic about the Astro platform, and will keep experimenting with Astro, being active in its unbelievably nice community (if those folks can tolerate me and my fickleness, that is), and hoping for a chance to re-implement it here in the not-too-distant future.
Note: Although it’s unrelated to the subject of this piece, you may be interested to know that I wrote this, at least in part, using the v.5 beta version of the venerable MultiMarkdown Composer. Also, it appears that the equally venerable iA Writer, my most frequent daily driver for these posts, soon will have a v.6 release. Each new major version will have been a long while coming; it was back in 2017 that MMDC reached v.4.0 and iA Writer reached v.5.0 (for iOS, at least, while the Mac version arrived in 2018).
Well, I say you must add a
setupitem. I suppose if you utterly don’t want to have a layout, much less add any components, you don’t have to use it; Astro will still build a page from the Markdown file. However, I can’t imagine you don’t want at least some layout. ↩︎In Eleventy and Hugo, you’d handle this
Boxstuff through attributes, a capability which is built into Hugo’s goldmark parser and added to Eleventy’s markdown-it parser through a plugin). This is not yet available in Astro if you’re using its default remark parser, because the appropriate plugin is incompatible with the current version of remark. (I haven’t tried Astro with a different parser, except in very small-scale, one-file-at-a-time tinkering with things like micromark and marked to make RSS and JSON feeds work better with Astro.) ↩︎However, editing CSS or SCSS doesn’t cause the same dragginess. ↩︎
Latest commit (ddfbbdb6) for page file:
2023-09-22 at 10:57:57 AM CDT.
Page history