Passing arguments to npm in PowerShell

This just caught me out. I was following the tutorial for the Astro web framework and it contains instructions to run this command:

npm create astro@latest -- --template minimal

The tutorial suggested you would then be prompted to enter a target directory.

Except I wasn't - I was seeing an interactive menu asking me to choose a template. This seemed weird as it kind of looks like the arguments above are telling it which template to use.

After a bit of experimenting I narrowed down the problem to running the command from PowerShell! (The command works fine in Bash or CMD). There's something in that line that PowerShell must be interpreting rather than just passing through to npm.

The solution that worked for me was to escape the dash. eg.

npm create astro@latest `-- --template minimal

With that, npm seems to see the correct arguments and runs as per the tutorial instructions.

Blog engine thoughts

Next month will mark the 20th year that I've been blogging. I started off in 2005 using Blogger, then in 2019 I migrated to Jekyll on GitHub Pages. I gained a lot more control over how how my blog is rendered to HTML, but one thing has always bothered me - I really don't understand Jekyll/Liquid/Ruby as well as I'd like, to be able to make customisations confidently.

Adopting a blog engine that uses a programming language that I have more experience with would go a long way to solving that. And that effectively narrows things down to C# and JavaScript/TypeScript.

The other constraint is that I'm really happy with having a static site. I don't want to have a database or any other backend resources - just generate the HTML pages that's it.

So looking around, the one .NET static engine I've encountered is Dave Glick's Statiq. This looked quite promising, and I did create a feature branch to try it out with my content. And that's where I hit some performance issues that seemed to relate to the Statiq.Web extension and the default blog template. As I already mentioned, I've been blogging for a while, and so when I count them all up, so far I have accumulated over 1100 posts! When I ran that feature branch on my full set of posts, it took 30 minutes on my i9 laptop (or almost an hour for the GitHub Action) to build the site. I did raise this at the time, but it hasn't been resolved, and development on Statiq seems to have largely stopped.

On the JavaScript/TypeScript side, I had noticed a lot of positive comments about Eleventy. Again, I spent a bit of time working on a feature branch to see how that could work, but I have to be honest I found the documentation a bit confusing. I do really prefer using TypeScript if possibly, and the support for that was not really first class.

Eleventy v3 was released late last year after I'd done my test run, so it could be worth revisiting.

Lastly, I wondered whether it was worth trying to do it all myself. I started to prototype out what this might look like at https://github.com/flcdrg/DaydreamEngine. I could potentially use ASP.NET Core's Razor components for managing layout with the ability to render them even when you're not running a web server.

Blog structure

One of the challenges I hit was thinking about the structure that is being generated, and trying to see how that would fit into the way the above blog engines seem to work.

Blogger

The old Blogger structure looked like this (Screenshot from Internet Archive's Wayback Machine):

Home page

• Title banner
• Last 2/3 posts in full
• Right hand sidebar
  • Links to other pages
  • Links to other blogs
  • Labels (categories)
  • List of years/month/posts
• Link to older posts (search)
• Footer

Individual posts are referenced using the following address format:

/2018/08/create-temporary-file-with-custom.html

Jekyll

Home page

• Title banner
• Last 3 posts in full
• No right hand sidebar
• Link to older posts (/page2,/page3,..page100)
• Footer

Individual posts use same address format as Blogger.

Future

Closer to the Blogger layout. Home page

• last 3 posts in full
• Right hand sidebar
  • Links to other pages
  • List of categories
  • Search facility
• Link to history
• Footer

I see some blogs that just put a summary of each post on the home page, requiring you to click on the link to read the full article.

The problem with the /page2,/page3 approach is that every time you add a new post, all the pages need to be rewritten. It inserts the new post at the front. It's the opposite of a traditional book or journal, where you would append new content at the end. I think this also means the /page2,/page3 confuse search engines a bit as the content keeps changing.

I think you still do need some kind of index/navigation page. Maybe having a year-based one would be more useful. I don't post enough that I think you need to break down a year into separate month pages.

So that's where I'm at for now. Another look at Eleventy v3, otherwise let's see what else I can implement in https://github.com/flcdrg/DaydreamEngine

The biggest problem with CI/CD pipelines

Do you know the most common problem I encounter when creating or updating build or deployment pipelines?

Finding the correct path to specific files!

I think that's why I find I have to litter my pipelines with extra steps like this:

- script: ls -alR
  displayName: "Script: List files"
  workingDirectory: $(Build.ArtifactStagingDirectory)

I think the problem is really that tools used to build software with, and the tasks you use in your pipelines, are so inconsistent with how they generate and reference files and paths.

For example:

• Does the file generated by a tool get created in a single directory, or does it create a child directory for the file to live in?
• If you use wildcards with the tool, does that change how it generates the output file(s)?
• Does the tool default to looking for files in the current working directory or somewhere else?
• If you use relative paths for tool parameters, are they relative to the current working directory, or to another specific parameter?
• If you're creating a zip file by pointing to a directory, does it include that directory in the zip, or just the child files and directories?
• Does the tool or task support wildcards? And are they 'normal' wildcards (aka globbing), or are they actually regular expressions?
• If the tool supports wildcards, can you specify multiple patterns, or only one?

I'm sure there are other variations. You get the idea at least.

And once you've finished banging your head against the wall and got all your path 'ducks' in a row, do you leave all those ls -alR tasks in your pipelines just in case you might need to refer to them in the future, or do you remove them to get rid of the extra noise (and make things a tiny bit faster)?

Using a tool like Cake as an abstraction over all your tools may help to a certain extent, as it then provides a more consistent interface in how you use the tools. But even then I've found myself having to add extra code in my .cake files to again list what files it can see to troubleshoot when things are not working as I think they should.

It's such a trivial thing, but it continues to trip me up, and I suspect I'm not alone 😀