Improvements to Deployment Documentation

[rowanc1]

Working through the deployment process for github pages on twitter with @LanaSina there are a number of improvements to make this clearer.

Overall the page should be structured as a tutorial with steps, with deployment instructions for each provider (github, curvenote, etc.). We should also not assume familiarity with github pages or actions. The content at the top of the page can be moved to a reference section, it is background and most people won't care, they just want to follow the steps and have it work!

Rough GitHub steps:

• Ensure your git is setup correctly
  • There should be a section somewhere on "What to commit to your Git repository", ideally we can add the _build folder to the .gitignore automatically.
• add a github action to the .github/workflow folder, include the file name. We could do this with a myst init --gh-action
• Explain what that does (or follow Deploy Pages directly from GitHub action #404).
• Wait for the actions to complete
• give a link to the github documentation (here and here) and show how to settings > pages > deploy from a branch > gh-pages.
• Wait for the deployment action to complete

Gotchas:

• pdf images don't convert on the actions

[LanaSina]

Other things that I needed to make it work:

In the GitHub action file change

• uses: actions/checkout@v2
• uses: actions/setup-node@v1
  To @V3 or you get a 'node12 deprecated' error (same resolution as this Node.js 12 to 16 actions/checkout#1047)

Also, after changing the BASE_URL env variable, the user should rerun the buil command, maybe? I'm not sure if that affects the GitHub deployment in any way.
Also by default the 'images' folder seems to be ignored by git, I don't know if that's intentional or not.

Big props to Rowan for patiently helping me over on Twitter when I was really getting frustrated a Saturday at midnight 😵‍💫

[rowanc1]

Progress has been made on getting the myst init --gh-pages function going:

I will get this pushed and deployed in the next few days.

[rowanc1]

I have made a pass at improving the documentation here:
https://mystmd.org/guide/deployment#deploying-to-github-pages

We just updated the CLI from myst-cli to mystmd, so you will have to uninstall/reinstall with that new name to get these changes. See #451.

Once you have the new version, I am hoping that myst init --gh-pages is fairly comprehensive, and then there are other notes in the docs.

I think @LanaSina that this would have gotten you up and running faster -- if you want to upgrade, you will have to switch to GitHub Actions as the source, and update the workflow YAML.

I am closing this issue, and will follow up on #452 later! Feel free to open it up again if the docs need updating.