some docs tweaks for new URL (deathbeds#15)

.github/workflows/badges.yml

@@ -16,5 +16,5 @@ jobs:
           script: |
             const issue_number = context.issue.number;
             const {repo, owner} = context.repo;
-            const body = `[![lite-badge](https://jupyak.rtfd.io/en/latest/_static/img/badge.svg)](https://jupyak--${issue_number}.org.readthedocs.build/en/${issue_number}) :point_left: Try it on ReadTheDocs`;
+            const body = `[![jupyak-badge](https://jupyak.rtfd.io/en/latest/_static/img/badge.svg)](https://jupyak--${issue_number}.org.readthedocs.build/en/${issue_number}) :point_left: Try it on ReadTheDocs`;
             github.rest.issues.createComment({issue_number, owner, repo, body});

README.md

@@ -9,55 +9,50 @@ This repo accepts [pull requests](#how-does-it-work) that build static [preview
 
 ## how do I get a preview site?
 
-- Use the _Request Preview Site_ form to propose a `jupyak_config.json` file to this repo
-  - or manually fork, clone, and build one
-    - the `.toml`, `.yaml`, and `.yml`) extensions are also discovered
-- Make a [pull request][pulls] to this repo
-- Wait for the PR to build a site on ReadTheDocs
-- Make changes to the _PR_ to trigger re-building the preview site
+- Make a `jupyak_config.toml`
+  - ... with the _Request Preview Site_ [form]
+  - ... or by manually [forking][fork] and creating a new branch from your fork
+- Start a [Pull Request][pulls] (PR) including the `jupyak_config.toml`
+- Wait for the PR to build a site on ReadTheDocs (RTD)
+- Make changes to the PR to trigger re-building the preview site
 
 ## where does it do it?
 
 - `https://github.com/deathbeds/jupyak`
     - a GitHub repo where the source code for this package, and all Issues, Pull Requests, and source code are stored
 - `https://deathbeds.github.io/jupyak`
-    - a GitHub Pages site, rebuilt nightly, which provides a form for building site requests
-- `https://jupyak.rtfd.io`
-    - a ReadTheDocs site for more information about how this all works
+    - a GitHub Pages site, rebuilt nightly, which provides a form for building preview site requests
 - `https://jupyak--{:pr-number}.org.readthedocs.build/en/{:pr-number}`
     - ReadTheDocs sites generated for each Pull Request
       - this will either be a
         - PR-based [preview site](#how-do-i-get-a-preview-site)
         - preview of the docs for the site itself
+- `https://jupyak.rtfd.io`
+    - a ReadTheDocs site for more information about how this all works
 
 > The above works on at least _one_ Ubuntu 22.03 LTS machine, but little care has
 > been taken to make _anything_ run on any other system, and likely won't be tested
 > anywhere else.
 
 ## how does it work?
 
-Delivering a preview site uses a few different GitHub Actions workflows and ReadTheDocs.
+Delivering a preview site uses a few different GitHub Actions workflows and ReadTheDocs
+configurations. Once a PR is created:
 
-- A nightly Github Actions job builds `https://deathbeds.github.io/jupyak`
-  - This site includes an HTML form of available PRs, tags, etc. for supported
-    [repos](#what-can-it-build).
-  - Clicking the _submit_ button will open a "new file" GitHub page against this repo
-  - Click _Commit Changes..._
-  - Follow the _Pull Request_ template and submit
-- A GitHub Action job will create a link to the current site
+- A GitHub Actions (GHA) job will create a link to the custom domain site
   - This will initially return `404`, as the site isn't built yet
   - Clicking instead on the ReadTheDocs check at the bottom of the Pull Request
     will show build logs, but these are _intentionally_ sparse, capturing most output
     as logs to present in the built site.
-- ReadTheDocs will check out the PR and build a preview JupyterLite site on a custom
-    domain
-  - If the preview site **fails** to build, the built RTD site will contain
-    human-readable error logs
+- RTD will check out the PR and build a preview JupyterLite site on a custom
+  domain
+  - If the preview site **fails** to build (or even check out due to conflicts),
+    the built RTD site will contain human-readable error logs
 - Additional commits on the PR can trigger a rebuild of the site
 
 ## what can it build?
 
-`jupyak` understand how to work with one or more human-readable URLs fragments of the forms:
+`jupyak` understand how to work with one or more fragments of human-readable GitHub URLs of the forms:
 
   - `/pull/{:pull-id}`
   - `/tree/{:branch}`
@@ -79,9 +74,10 @@ Delivering a preview site uses a few different GitHub Actions workflows and Read
   - https://github.com/jupyterlite/jupyterlite
   - https://github.com/jupyterlite/pyodide-kernel
 
-Additionally, a single GitHub gist can be used as the contents of the preview site,
-and can further configure the build- and runtime behavior of JupyterLite by providing
-a custom `jupyter_lite_config.json` and/or `jupyter-lite.json`.
+Additionally, a single GitHub [Gist][gist] can be used as the contents of the preview site.
+If the gist contains `jupyter_lite_config.json` and/or `jupyter-lite.json`, these
+will be merged into the [configuration][lite-config] used to build and host the site.
+
 
 ## what does it _not_ build?
 
@@ -99,3 +95,9 @@ chance of a usable JupyterLite site at the end of each PR build. These include:
 
 [issues]: https://github.com/deathbeds/jupyak/issues
 [pulls]: https://github.com/deathbeds/jupyak/pulls
+[form]: https://deathbeds.github.io/jupyak/new.html
+[fork]: https://github.com/deathbeds/jupyak/fork
+[gist]: https://gist.github.com/
+[pages-badge]: https://github.com/deathbeds/jupyak/actions/workflows/pages.yml/badge.svg?branch=main
+[pages-status]: https://github.com/deathbeds/jupyak/actions/workflows/pages.yml
+[lite-config]: https://jupyterlite.readthedocs.io/en/latest/howto/configure/config_files.html

docs/_templates/new-form.html

@@ -25,7 +25,7 @@
       <input type="hidden" name="filename" value="jupyak_config.toml"/>
       <br/>
       <button class="btn btn-success" form="propose">
-        <i class="fas fa-code-pull-request"></i> New Pull Request
+        <i class="fas fa-github-alt"></i> new pull request...
       </button>
     </form>
   </div>