I followed the tutorial and installed Ghost locally on my computer tonight because I wanted to try to customize my theme. I’m currently on a Ghost(Pro) trial and everything is looking promising. But when I use the Gallery on my local machine, it doesn’t work. If I use it on Ghost(Pro) it does.
On my local machine, everything looks good in draft mode:
Note that I’m not using the beta editor. I’m also using the Dawn 1.0 theme but I’m pretty sure that’s not the issue because I’m using that same theme on my Ghost(Pro) instance which works fine.
It’s not just the Gallery either, btw. Video and buttons are also broken as well if I use those widgets. It’s almost like some CSS is not loading. In the console, I see this error but Idk if it’s related :
GET http://localhost:2368/public/member-attribution.min.js?v=c25ff37a15 net::ERR_ABORTED 404 (Not Found)
Has anyone encountered this issue? Here’s the Ghost version I’m using locally (just installed it tonight):
There’s a known bug with generating of card assets on windows, and that looks like what you’re seeing here.
I do all my developing on a windows laptop, too. My preferred solution is to use WSL, which gets you Ubuntu running on your Windows machine. (While still running Windows! It’s like magic…) That causes this bug (and a few other Windows gremlins) not to occur.
Install WSL:
Then once you’ve got a WSL terminal open, follow the Linux Ghost install directions.
PS. IMHO, if there are known issues with local installs on Windows (eg. Card assets flat out not working, out-of-the box, I think they should better publicize that on the “How to install Ghost locally” page. Because currently, that page just lists prerequisites as "A computer running MacOS, Windows or Linux", which is a bit misleading!
I agree. Hey @RyanF, here’s a spot the documentation could be improved! :) You could borrow @mheland 's documentation here (with permission, I mean…) as a starting point!
There’s an issue open on Github with a PR to fix it, but if it isn’t going to get accepted*, fixing the docs to prevent Windows-using theme editors from splatting on it would significantly reduce rookie dev frustration. Installing WSL is a bit slow (especially on slow internet), but it’s the difference between everything just working and various subtle differences that are frustrating.
*And I totally understand that a bug that only hits users running on locally Windows without WSL is not very high on the dev team priority list. No criticism of the devs intended, but I /do/ hope we can get the docs improved!
Now I’m curious how the resulting Mobiledoc code for the cards differs when generated on Windows vs In WSL. I wonder what difference that environment could be making!
The only thing that comes to made immediately would be “windows line breaks” vs “unix line breaks”, but I don’t know what would matter.
The issue is documented and being worked on. See the issue if you want a deep dive into what’s happening.
I don’t have an ETA for a fix, but I think the best solution at the moment is to use WSL. In general, WSL + Windows Terminal is going to give you the best experience when doing Ghost/Theme development.
We have basic instructions on installing WSL here:
FWIW, when I’m developing on Windows (which is usually for all my personal projects), I use Windows Terminal with WSL. In Ubuntu, I use ZSH.
In Ubuntu, I’ll usually have a sites directory, where I keep my installations of Ghost, and then a separate themes directory, where I keep the themes I’m working on. I’ll symlink the theme into the content/themes folder of the Ghost installation. In the theme folder, I use code . to open the theme in VS Code (I don’t think I need any special kind of extension, but I think VSC does some magic to install compatible versions of things in the background.). Then, I start my dev server npm run dev or whatever you’re using. This works really well for me, but I’m keen to know other people’s workflows, too.
I use the VSCode built in terminal (which I think is basically powershell). I’m often on one screen and a laptop at that, so it’s nice to have it all in one place.
I’ve been meaning to try your link strategy, RyanF. Seems like it’d be really useful. Do you initially install the theme by uploading a zip? It’s been my experience (possibly setup dependent) that Ghost doesn’t just recognize things dropped into the themes folder otherwise, but I’m interested if there’s a better way.
The initial install is done via symlinking the folder. ln -s path/to/theme . However, you need to restart Ghost because it only scans the folder for changes at start. Then, the theme should be available in the Design settings for activation.
My main motivation for doing this is that there’s been more than one occasion where I’ve uploaded a theme only to overwrite changes I hadn’t saved yet . Keeping the theme separate prevents this from happening but also lets you see instant changes during development.
I did dig through the GitHub issue and see that it dates back to Mar 7, 2022.
I agree with @Cathy_Sarisky. As a total Ghost newb, it was really disappointing and frustrating to have encountered this issue right out of the gate. Judging from the GitHub issue, I suspect I’m not alone either. Here’s one of the comments in that issue:
So far, I’m loving Ghost though! I understand it’s a small team. This is just my 2c, but I honestly feel in the documentation, everywhere, you should just outright make explicit that Ghost is only supported on Windows via WSL. Bc the way it’s currently written, that’s definitely not made clear. Now WSL exists, I feel it’d make the most sense to simply put all of your development effort and resources into the MacOS/Linux build and not even make any pretense of being Windows-native compatible at all. As a lifelong Windows developer, I say this in full sincerity: It’s just not worth it. On Windows, things are just outright worse in the opensource world. Everything from carriage returns/newlines to Node package support to datetime shenanigans.
It’s 2023 and Nadella’s at the helm now. Linux for opensource for the win!!
Thanks for reporting back, and I’m glad the switch to WSL fixed things for you!
I agree with this!
@RyanF, yes, the docs mention that WSL is an option, but it’d be nice if the docs said that WSL is the /best/ option, rather than “Windows users have another option” (what the documentation currently says). We want more rookie Ghost users who’d like to customize their themes to be able to launch successfully. This is an unnecessary frustration.
@Cathy_Sarisky re the sym-linking theme dev workflow strategy, @RyanF actually posted a nice walkthrough and vid that I was able to successfully follow this afternoon on my Windows machine.
In the YT vid, Ryan walks through using degit to clone the ghost starter theme from GitHub onto your local machine and then sym-linking it to a local ghost installation with ln -s. Personally, I like these developer ergonomics a lot! Especially with the hot reloading that shows theme changes live as I tweak stuff in VS Code.
:
. Keeping the theme separate prevents this from happening but also lets you see instant changes during development.
Judging from the GitHub issue, I suspect I’m not alone either. Here’s one of the comments in that issue: