Pxt-sample todo list / pxt staticpkg to github doesn't update right?

I am in the middle of making a pxt but I am having some difficulty following the pxt-sample instructions.

So far I have completed

  • Fork repo and setup local server (see below)
  • Update metadata in pxtarget.json . Change the id, title, name, etc… to your taste.
  • Update the JavaScript runtime in sim/simulator.ts . If needed add additional JS library under sim/public/** and edit sim/public/simulator.html with additional script tags.
  • Update the APIs in sim/api.ts to use your runtime.
  • Test your editor in the local server

But am stuck on

run pgk staticpkg --gh --bump to upload a static version to GitHub pages.

I assume this is pxt staticpkg --route myrepositoryname --bump --githubpages

But I’m a little confused on what this step does. I was able to publish once using this tool but I was not able to successfully update using this method? It’s a bit of a black box what’s happening.

Any thoughts would be lovely?

Ok I kinda worked out a solution, having read the sources now for staticpkg I think I get what it’s trying to do?

The webpages on github are served out a branch called gh-pages. It builds and as part of that process it stuffs static html into that branch. Except that whatever I did made it go crazy town and I had about 3 different copies stored in the same branch in all different locations. Swapping back and forth between the branches on my machine blew away my node modules folder which was a bit annoying when tracking down the problem.

To work around staticpkg --github not rendering images, and also being a bit too “automagic” - I both separated out the folders - one folder for each branch and created a new repo for docs.

Make a separate folder for your github website
This makes life easier not switching between branches and losing node modules, etc.

First time only, make a second copy of your repository on your machine that is always in the webpage branch

  • Make a new folder on your machine: makecode-gh-pages
  • cd makecode-gh-pages
  • git clone YOUR_REPOSITORY
  • git checkout gh-pages

Now you will permanently have the static webpage in a folder on your machine.

Building without the --github flag

  • Go back to your original folder (where you run pxt serve out of normally)
  • Run pxt serve
  • Run pxt staticpkg --route YOUR_REPOSITORY --output ./built/gh-pages
  • Your static website will be built, a copy of which will be on your machine in YOUR_REPOSITORY/built/gh-pages folder.

Copy the built website out to the gh-pages branch for publishing

  • cp -R ./built/gh-pages/YOUR_REPOSITORY ../makecode-gh-pages/

Then go back to your makecode-gh-pages repo, review and commit your changes.

To get images to load:
There is a bug in staticpkg/pxtembed, etc where all the images generated do not honour the --route you passed in.

Create a completely different repo in your github account called docs, I popped mine inside the makecode-gh-pages folder so they’re all together.

  • go to github and make a new repository for your account called docs
  • cd where-ever you put makecode-gh-pages… cd makecode-gh-pages
  • copy YOUR_REPOSITORY/docs to makecode-gh-pages/docs
  • make and publish a gh-pages branch on the docs repo

And now your images will be served out of the docs repo.

Thoughts appreciated…