Clarify ways to acess the R WASM package

README.md

@@ -182,16 +182,42 @@ specified in the `packages` file setup above.
 
 ## Usage inside webR
 
-Inside of a webR session, you can access the built binaries by using the
-repository’s GitHub Pages URL, e.g.
+## Accessing Binaries
+
+In a webR session, access the built binaries using the repository’s
+GitHub Pages URL, for example:
 
     https://gh-username.github.io/repo-name
 
-This can be set either using `options()` or specifying the location in
-each `webr::install()` call.
+Depending on where you are using the custom R WASM package binary, you
+can register this repository in different ways:
+
+1.  Using the `repos` key inside of the `quarto-webr` extension;
+2.  Using `options()` to set values for both `repos` and
+    `webr_pkg_repos`; or,
+3.  Using the `repos` parameter in each `webr::install()` call.
+
+### `repos` Document key in `{quarto-webr}`
+
+With version v0.4.0 of the `{quarto-webr}` extension, the repository can
+be included by using the [`repos` key in the document
+header](https://quarto-webr.thecoatlessprofessor.com/qwebr-using-r-packages.html#custom-repositories):
+
+``` md
+---
+webr:
+  packages: ['pkgname']
+  repos:
+    - https://gh-username.github.io/repo-name
+filters:
+ - webr
+---
+```
+
+### Specifying repo urls with `options()`
 
-The easiest is probably to define the location webR should search for in
-`options()`.
+To define the location webR should search for in `options()`, we need to
+set both `repos` and `webr_pkg_repos`.
 
 ``` r
 ## Run once at the start of the session
@@ -200,6 +226,7 @@ The easiest is probably to define the location webR should search for in
 list_of_repos = c(
     "https://gh-username.github.io/repo-name", 
     "https://other-gh-username.github.io/another-repo", 
+    "https://username.r-universe.dev", 
     "https://repo.r-wasm.org/"
   )
 
@@ -213,34 +240,36 @@ options(
 webr::install("pkgname")
 ```
 
-Otherwise, the `repos` can be specified each time:
+> [!NOTE]
+>
+> This is different than the `repos` option one would usually set since
+> webR only checks the [`webr_pkg_repos`
+> key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23);
+> however, other R functions like `available.packages()` check the
+> `repos` parameter.
+
+### Specifying `repos` in `webr::install()`
+
+The `repos` parameter may also be specified in the `webr::install()`
+command each time you need to install a package from a custom location:
 
 ``` r
 webr::install("pkgname", repos = "https://gh-username.github.io/repo-name")
 
 webr::install("pkgname", repos = list_of_repos)
 ```
 
-<div>
-
-> **Important**
+> [!IMPORTANT]
 >
-> Please make sure the repository’s [GitHub Pages website is available
-> over
+> Ensure the repository’s [GitHub Pages website is available over
 > `HTTPS`](https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#enforcing-https-for-your-github-pages-site)
-> not `HTTP` (notice the lack of an `s`). You can verify this option was
-> selected by:
+> (not `HTTP`). Verify this option in the repository’s **Settings** page
+> under **Code and automation** \> **Pages** \> **Enforce HTTPS**.
 >
-> 1.  Going to the repository’s **Settings** page
-> 2.  Selecting **Pages** under **Code and automation**
-> 3.  Checking the **Enforce HTTPS** button.
->
-> Otherwise, you will receive the error message of:
+> Otherwise, you might encounter an error:
 >
 >     Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3
 
-</div>
-
 ## Verify
 
 Go to the [webR REPL Editor](https://webr.r-wasm.org/v0.2.2/) (pinned to

README.qmd

@@ -152,26 +152,50 @@ where `mypackage_1.0.0` should resemble the names of the packages specified in t
 
 ## Usage inside webR
 
-Inside of a webR session, you can access the built binaries by using the
-repository’s GitHub Pages URL, e.g.
+## Accessing Binaries
+
+In a webR session, access the built binaries using the repository's GitHub Pages URL, for example:
 
 ```
 https://gh-username.github.io/repo-name
 ```
 
-This can be set either using `options()` or specifying the location in
-each `webr::install()` call.
+Depending on where you are using the custom R WASM package binary, you can 
+register this repository in different ways: 
 
-The easiest is probably to define the location webR should search for in
-`options()`.
+1. Using the `repos` key inside of the `quarto-webr` extension;
+2. Using `options()` to set values for both `repos` and `webr_pkg_repos`; or,
+3. Using the `repos` parameter in each `webr::install()` call. 
 
-``` r
+### `repos` Document key in `{quarto-webr}`
+
+With version v0.4.0 of the `{quarto-webr}` extension, the repository
+can be included by using the [`repos` key in the document header](https://quarto-webr.thecoatlessprofessor.com/qwebr-using-r-packages.html#custom-repositories):
+
+```md
+---
+webr:
+  packages: ['pkgname']
+  repos:
+    - https://gh-username.github.io/repo-name
+filters:
+ - webr
+---
+```
+
+### Specifying repo urls with `options()`
+
+To define the location webR should search for in `options()`, we need to
+set both `repos` and `webr_pkg_repos`. 
+
+```r
 ## Run once at the start of the session
 
 # Specify where to search for the R WASM packages
 list_of_repos = c(
     "https://gh-username.github.io/repo-name", 
     "https://other-gh-username.github.io/another-repo", 
+    "https://username.r-universe.dev", 
     "https://repo.r-wasm.org/"
   )
 
@@ -185,33 +209,32 @@ options(
 webr::install("pkgname")
 ```
 
-Otherwise, the `repos` can be specified each time:
+:::{.callout-note}
+This is different than the `repos` option one would usually set since webR only checks the [`webr_pkg_repos` key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23); however, other R functions like `available.packages()`
+check the `repos` parameter.
+:::
+
+### Specifying `repos` in `webr::install()`
+
+The `repos` parameter may also be specified in the `webr::install()` command
+each time you need to install a package from a custom location:
 
 ```r
 webr::install("pkgname", repos = "https://gh-username.github.io/repo-name")
 
 webr::install("pkgname", repos = list_of_repos)
 ```
 
-<div>
-
-> **Important**
->
-> Please make sure the repository’s [GitHub Pages website is available
-> over
-> `HTTPS`](https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#enforcing-https-for-your-github-pages-site)
-> not `HTTP` (notice the lack of an `s`). You can verify this option was
-> selected by:
->
-> 1.  Going to the repository’s **Settings** page
-> 2.  Selecting **Pages** under **Code and automation**
-> 3.  Checking the **Enforce HTTPS** button.
->
-> Otherwise, you will receive the error message of:
->
->     Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3
-
-</div>
+:::{.callout-important}
+
+Ensure the repository's [GitHub Pages website is available over `HTTPS`](https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#enforcing-https-for-your-github-pages-site) (not `HTTP`). Verify this option in the repository's **Settings** page under **Code and automation** > **Pages** > **Enforce HTTPS**.
+
+Otherwise, you might encounter an error:
+
+```
+Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3
+```
+:::
 
 ## Verify