📖 Add deployment docs on netlify (#1125)

docs/_toc.yml

@@ -46,6 +46,10 @@ parts:
       - file: analytics
       - file: website-downloads
       - file: deployment
+        sections:
+          - file: deployment-github-pages
+          - file: deployment-curvenote
+          - file: deployment-netlify
       # - file: publishing
   - caption: Documents
     chapters:

docs/deployment-curvenote.md

@@ -0,0 +1,56 @@
+---
+title: Deploying to Curvenote
+short_title: Curvenote
+description: Deploy your MyST site to Curvenote
+---
+
+Curvenote provides a free service to host your MyST sites with an up-to-date theme ([deployment documentation](https://github.com/curvenote/action-myst-publish) for MyST sites). The websites are hosted on a `curve.space` subdomain with your username or a [custom domain](https://curvenote.com/docs/web/custom-domains). To configure the domain(s) add them to your site configuration:
+
+```yaml
+site:
+  domains:
+    - username.curve.space
+```
+
+You can then deploy the site using:
+
+```bash
+curvenote deploy
+```
+
+You can also deploy from a GitHub action, which will build your site and then deploy it to Curvenote.
+
+🛠 In the root of your git repository run `myst init --gh-curvenote`
+
+The command will ask you questions about which branch to deploy from (e.g. `main`) and the name of the GitHub Action (e.g. `deploy.yml`). It will then create a GitHub Action[^actions] that will run next time you push your code to the main branch you specified. Ensure that you including setting up your `CURVENOTE_TOKEN` which can be created from your Curvenote profile.
+
+:::{tip} Full GitHub Actions
+:class: dropdown
+
+You can use GitHub actions to build and deploy your site automatically when you merge new documents, for example.
+
+See the documentation for the action, including setting up your `CURVENOTE_TOKEN`:\
+https://github.com/curvenote/action-myst-publish
+
+```yaml
+name: deploy-myst-site
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy 🚀
+        uses: curvenote/action-myst-publish@v1
+        env:
+          CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }}
+```
+
+:::
+
+[^actions]: To learn more about GitHub Actions, see the [GitHub documentation](https://docs.github.com/en/actions/quickstart). These are YAML files created in the `.github/workflows` folder in the root of your repository.

docs/deployment-github-pages.md

@@ -0,0 +1,101 @@
+---
+title: Deploying to GitHub Pages
+short_title: Github Pages
+description: Deploy your MyST site to GitHub pages with a single command.
+---
+
+GitHub Pages[^pages] allows you to host your project in a folder, which is your repositories name, for example:\
+`https://owner.github.io/repository_name`\
+To get setup with GitHub Pages, ensure that your repository is hosted in GitHub and you are in the root of the Git repository.
+
+🛠 In the root of your git repository run `myst init --gh-pages`
+
+The command will ask you questions about which branch to deploy from (e.g. `main`) and the name of the GitHub Action (e.g. `deploy.yml`). It will then create a GitHub Action[^actions] that will run next time you push your code to the main branch you specified.
+
+:::{figure} ./images/myst-init-gh-pages.png
+:class: framed
+The command `myst init --gh-pages` will guide you through deploying to GitHub Pages.
+:::
+
+[^actions]: To learn more about GitHub Actions, see the [GitHub documentation](https://docs.github.com/en/actions/quickstart). These are YAML files created in the `.github/workflows` folder in the root of your repository.
+[^pages]: To learn more about GitHub Pages, see the [GitHub documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
+
+Navigate to your repository settings, click on Pages and enable GitHub pages. When choosing the source, use `GitHub Actions`:
+
+🛠 Turn on GitHub Pages using **GitHub Actions** as the source.
+
+To trigger action, push your code with the workflow to main.
+
+:::{warning} Custom Domains
+GitHub allow you to host your static content on a custom domain, doing so _may_ require you to change the `BASE_URL` environment variable in the action. If you have unstyled content, try changing the `BASE_URL` to a blank string: `BASE_URL=''` (note the **single quotes**!); this serves the build assets from the root of your domain, rather than the default, which is the name or your repository.
+:::
+
+:::{tip} `BASE_URL` environment variable
+:class: dropdown
+The build and site assets are in the `/build` folder, which would point outside of the current repository to a repository called 'build', which probably doesn't exist!
+
+To fix this, we can change the base url that the site is mounted to, which can be done through the `BASE_URL` environment variable:
+
+```bash
+export BASE_URL="/repository_name"
+```
+
+The base URL is _absolute_ and should not end with a trailing slash. This can be done automatically in a GitHub Action by looking to the `github.event.repository.name` variable.
+:::
+
+:::{note} Full GitHub Action
+:class: dropdown
+
+The GitHub Action to build and deploy your site automatically is:
+
+```{code} yaml
+:filename: deploy.yml
+# This file was created automatically with `myst init --gh-pages` 🪄 💚
+
+name: MyST GitHub Pages Deploy
+on:
+  push:
+    # Runs on pushes targeting the default branch
+    branches: [main]
+env:
+  # `BASE_URL` determines the website is served from, including CSS & JS assets
+  # You may need to change this to `BASE_URL: ''`
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install MyST Markdown
+        run: npm install -g mystmd
+      - name: Build HTML Assets
+        run: myst build --html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+```
+
+:::

docs/deployment-netlify.md

@@ -0,0 +1,106 @@
+---
+title: Deploying to Netlify
+short_title: Netlify
+description: Deploy your MyST site to Netlify
+---
+
+% Adapted from: https://jupyterbook.org/en/stable/publish/netlify.html#step-2-add-the-command-to-install-and-build-your-book
+
+[Netlify](https://www.netlify.com/) is a continuous deployment service that can
+**automatically build an updated copy of your project** as you push new content.
+It can be used across git clients including GitHub, GitLab, and Bitbucket.
+Although Netlify has both free and paid tiers, the build process is the same across both.
+Importantly, the free tier only allows for 100GB of bandwidth usage per month across all of your Netlify built projects[^pricing].
+
+[^pricing]: If your project will be used by a large audience, or if you're creating many projects, you might want to consider registering for [a paid account](https://www.netlify.com/pricing/).
+
+These instructions assume you're keeping your source files under version control,
+rather than the built project HTML.
+
+In order to use Netlify, you'll need to [create an account](https://app.netlify.com/signup).
+Here, we'll walk through connecting your project to Netlify's continuous deployment services using their UI.
+You can also check out their [documentation on continuous deployment](https://www.netlify.com/docs/continuous-deployment/).
+
+## Step 1: Connect your GitHub repo to Netlify
+
+After you've created a Netlify account, you'll need to log in.
+The home page will be a dashboard of all sites you're currently building with Netlify.
+We can then import a new site by clicking the "New Site from Git" button in the upper right.
+
+This should launch [the site builder](https://app.netlify.com/start):
+
+![Netlify site builder](./images/netlify-new-site.png)
+
+Here, you can select the git client where your project is hosted.
+For the purposes of this tutorial, we'll assume that your book is hosted on GitHub.
+
+When you select the "GitHub" option, you'll be asked to grant permission for Netlify to access your GitHub account.
+Authorizing access will take you to the next step of the build process, where you can select your project repository.
+
+![Netlify continuous deployment](./images/netlify-cd.png)
+
+## Step 2: Add the command to install and build your project
+
+:::{note}
+If your book content is not in the root of your repository, make sure you point to
+where you will run the `myst build --html` command locally.
+:::
+
+Once you've selected the correct repository, you'll need to supply build instructions.
+This is a command that Netlify runs before hosting your site. We'll use it to do the
+following:
+
+- Install `mystmd`
+- Build your project's HTML
+
+Put the following command in the _Build command_ section:
+
+```bash
+npm install -g mystmd && myst build --html
+```
+
+Finally, the _Publish directory_ should be `_build/html`.
+
+You'll also need to select the appropriate branch to build your repository from.
+In this example, we'll use the `main` branch.
+
+![Netlify build command](./images/netlify-build-settings.png)
+
+You can then select _Deploy site_ and wait for the site to build.
+You'll be redirected to the site dashboard during the build process.
+
+## Step 3: Updating your domain name
+
+If your site has successfully built, it will be assigned a random domain name.
+In order to have a more memorable address, you can update your site's name.
+
+From the site dashboard, select _Domain settings_.
+This will take you to a sub-menu, where you can choose to update your site name.
+
+![Netlify configure domain](./images/netlify-domains.png)
+
+You can enter a memorable, unique name here to describe your project!
+Note that it will be prepended to `.netlify.com` so, `MY-BOOK` will become `MY-BOOK.netlify.com`.
+
+You can also use a custom domain (i.e., one that you have purchased through a DNS registrar).
+See the [Netlify documentation on custom domains](https://www.netlify.com/docs/custom-domains/) for more details on this process.
+
+<!--
+## Step 4: Adding Compute
+
+You can also install dependencies for executing notebooks, this will require a few changes to your configuration above.
+
+:::{warning}
+The default Netlify Python environment is Python 2.7.
+You should update the Python environment by including a `runtime.txt` file in your repository,
+as detailed in [the Netlify documentation](https://www.netlify.com/docs/build-settings/#build-environment-variables).
+
+For a full list of available environments,
+please see the [Netlify build image details](https://github.com/netlify/build-image/blob/xenial/included_software.md#languages).
+:::
+
+:::{note}
+Ensure that project's version in your `requirements.txt` file is at least
+`0.7.0`.
+:::
+ -->