Improve startup docs

Convert screenshots to PNG, optimize PNGFix Apollo version
Fix Apollo version
Typo
Add NPM and Docker version of CLI in startup guide


skip-checks:true

packages/website/blog/2024/12-17-beta-release.md

@@ -5,7 +5,7 @@ authors: garrettjstevens
 # Apollo 3 Genome Annotation Editor - Beta Release
 
 Thank you to all those who have shown an interest in Apollo 3, our tool for
-collaborative genome annotation.Due to Apollo 3’s flexible client-server
+collaborative genome annotation. Due to Apollo 3’s flexible client-server
 architecture, there are a few different ways you can use it, both single-user to
 collaborative, and using demo servers or configuring your own data. We would
 like to introduce four different ways you can try out Apollo, ranging from

packages/website/docs/getting-started/try-it-out/01-setting-up.md

@@ -3,7 +3,11 @@
 To run this demo, you'll need to have
 [Docker](//docs.docker.com/engine/install/) (minimum version 27) and
 [Docker Compose](//docs.docker.com/compose/install/) (minimum version 2.17.0)
-installed.
+installed, as well as [`jq`](https://jqlang.github.io/jq/).
+
+We also recommend a Node.js package manager (such as `npm` or `yarn`) to make
+things a easier, but we will provide directions for doing everything without one
+that you can follow if you prefer.
 
 ## Getting the data
 
@@ -75,7 +79,7 @@ services:
         wget https://github.com/GMOD/jbrowse-components/releases/download/v2.18.0/jbrowse-web-v2.18.0.zip --output-document=jbrowse-web.zip
         unzip -o jbrowse-web.zip
         rm jbrowse-web.zip
-        wget --output-document=- --quiet https://registry.npmjs.org/@apollo-annotation/jbrowse-plugin-apollo/-/jbrowse-plugin-apollo-0.2.2.tgz | \
+        wget --output-document=- --quiet https://registry.npmjs.org/@apollo-annotation/jbrowse-plugin-apollo/-/jbrowse-plugin-apollo-0.3.0.tgz | \
         tar --extract --gzip --file=- --strip=2 package/dist/jbrowse-plugin-apollo.umd.production.min.js
         mv jbrowse-plugin-apollo.umd.production.min.js apollo.js
         wget --quiet https://github.com/The-Sequence-Ontology/SO-Ontologies/raw/refs/heads/master/Ontology_Files/so.json

packages/website/docs/getting-started/try-it-out/02-loading-data.md

@@ -1,18 +1,53 @@
 # Loading data
 
-## Setting up the Apollo CLI
+## Setting up the Apollo and JBrowse CLI
 
-The Apollo CLI is used to configure and load data into Apollo. We'll need a
-config file for our CLI configuration. For simplicity, we'll create an empty
-file called `config.yml` in a new directory.
+Both Apollo and JBrowse have CLI tools that you can use to load data. The
+recommended way to install both these tools is through a Node.js package manager
+(such as `npm` or `yarn`). See
+[the next section](#installing-cli-tools-with-npm-or-yarn) for those
+installation instructions.
+
+If you would rather use Docker to run the CLI tools, it is possible to do so
+with a bit more setup. See
+[this section](#setting-up-docker-to-run-the-cli-tools) for those instructions.
+
+### Installing CLI tools with `npm` or `yarn`
+
+Use the following to install the Apollo and JBrowse CLI tools.
+
+```bash npm2yarn
+npm install -g @apollo-annotation/cli @jbrowse/cli
+```
+
+You can test that those commands work by running `apollo --version` and
+`jbrowse --version` in your terminal. The output should look something like
+this:
+
+```sh-session
+$ apollo --version
+@apollo-annotation/cli/0.3.0 linux-x64 node-v18.20.4
+$ jbrowse --version
+@jbrowse/cli/2.18.0 linux-x64 node-v18.20.4
+```
+
+If that worked, you can move on to
+[configuring the Apollo CLI](#configuring-the-apollo-cli).
+
+### Setting up Docker to run the CLI tools
+
+Apollo provides a Docker image of its CLI. In order to configure the Apollo CLI
+in the Docker container, though, you'll need to create a config file for it
+first. For this guide, we'll create an empty file called `config.yml` in a new
+directory.
 
 ```sh
 mkdir cli
 touch cli/config.yml
 ```
 
-We'll use Docker to run the Apollo CLI. To avoid having to re-type the Docker
-commands, we use this function:
+Now we'll create a function that wraps the Docker commands that we need to run
+to avoid having to re-type them. Run the following in your terminal:
 
 ```sh
 function apollo() {
@@ -28,25 +63,52 @@ function apollo() {
 }
 ```
 
-Paste and run the above command in your terminal to create the function, then
-run `apollo --version` in your terminal. You should see something like this
+Now run `apollo --version` in your terminal. You should see something like this
 output:
 
-```
+```sh-session
 $ apollo --version
-@apollo-annotation/cli/0.1.20 linux-x64 node-v18.20.4
+@apollo-annotation/cli/0.3.0 linux-x64 node-v18.20.4
 ```
 
-:::tip
+JBrowse does not provide a Docker image for its CLI, so we'll have to create
+one. Create a file called jbrowse.Dockerfile and paste the following contents
+into it:
+
+```Dockerfile title="jbrowse.Dockerfile"
+FROM node:18-alpine
+RUN mkdir data && yarn global add @jbrowse/cli
+ENTRYPOINT ["jbrowse"]
+```
 
-If you're familiar with installing Node.js packages you can install the Apollo
-CLI instead of using Docker.
+Now run this command:
 
-```bash npm2yarn
-npm install -g @apollo-annotation/cli
+```
+docker build --tag jbrowse-cli --file jbrowse.Dockerfile .
 ```
 
-:::
+When that is done, we'll create a wrapper function like we did for the Apollo
+CLI.
+
+```sh
+function jbrowse() {
+  docker \
+    run \
+    --rm \
+    --interactive \
+    --volume ./data:/data \
+    jbrowse-cli \
+    "$@"
+}
+```
+
+After pasting that into your terminal, run `jbrowse --version` and check that
+the output looks something like this:
+
+```sh-session
+$ jbrowse --version
+@jbrowse/cli/2.18.0 linux-x64 node-v18.20.4
+```
 
 ## Configuring the Apollo CLI
 
@@ -56,19 +118,14 @@ Apollo installation. You can have multiple profiles configured, but we will use
 a single default profile. Run these commands:
 
 ```sh
-apollo config address http://host.docker.internal/apollo
+apollo config address http://localhost/apollo
+# If you are using Docker to run the Apollo CLI, then instead you need to do:
+# apollo config address http://host.docker.internal/apollo
 apollo config accessType root
 apollo config rootPassword password
 apollo login
 ```
 
-:::tip
-
-If you're using the Apollo CLI installed from NPM, change the first line above
-to `apollo config address http://localhost/apollo`.
-
-:::
-
 If you need to log in again, run `apollo logout` first, or use
 `apollo login --force`.
 

packages/website/docs/getting-started/try-it-out/03-annotating.md

@@ -20,23 +20,23 @@ put the above region in the location box and press "Enter".
 Click "Open track selector". Select track called "Annotations (Schistosoma
 mansoni)".
 
-![Track selector](track-selector.svg)
+![Track selector](track-selector.png)
 
 Try out clicking and dragging to move back and forth, as well as using the arrow
 buttons in the header. Also try out clicking the zoom buttons.
 
 Let's focus on the end of the CDS. If we hover over the warning, we'll see that
 the CDS is missing a stop codon.
 
-![CDS warning](cds-warning.svg)
+![CDS warning](cds-warning.png)
 
 Click and drag in the ruler the area around the end of the CDS and then select
 "Zoom to region". We can see that the CDS stop short of the stop codon. Click
 and drag the right side of the CDS 3 bases to the right to fix it. Zoom back out
 so you can see the whole gene again, and you will see the warning about the stop
 codon is gone as well.
 
-![Fixing the stop codon](fix-stop-codon.svg)
+![Fixing the stop codon](fix-stop-codon.png)
 
 Now click the checkbox to open the RNA-seq track. It looks like this feature's
 3\` UTR is actually longer. Let's extend the exon to fix that. Click on the
@@ -46,7 +46,7 @@ the current annotation is now shown at the bottom of the track. In the "gene"
 row, change then "end" value to `9659388`, and then do the same for the "mRNA"
 column.
 
-![RNA-seq table editor](rnaseq-table-editor.svg)
+![RNA-seq table editor](rnaseq-table-editor.png)
 
 We could also do the same for the exon, but we'll do it a different way as a
 demonstration. Right-click on the exon and choose "Edit feature details". Change
@@ -56,21 +56,21 @@ Next click "Add new" in that same panel and add "Note" as a custom attribute
 key. Click "Add", and then in the newly added "Note" attribute, add some text
 (e.g. "UTR extended due to RNA-seq evidence").
 
-![Extend exon](extend-exon.svg)
+![Extend exon](extend-exon.png)
 
 Now re-open the track selector and select the synteny track (_S. haematobium vs.
 S. mansoni TBLASTX_). Right-click on one of the features and choose "Open
 synteny view for this position". Leave the default and click "Submit". Then
 close your original Linear Genome View by clicking on the cross circled in red.
 
-![Open synteny track](open-synteny-track.svg)
+![Open synteny track](open-synteny-track.png)
 
 Click "Open track selector" on the top track and then open the Annotations and
 RNA-seq tracks. Do the same on the bottom view. We might want the annotations
 closer to each other, so in the top view, open the track selector of the RNA-seq
 track and select "Track order -> Move track up".
 
-![Synteny tracks](synteny-tracks.svg)
+![Synteny tracks](synteny-tracks.png)
 
 If you wanted to share this particular view, you can click the "Share" button at
 the top and copy the link. You can also use this for coming back to the same
@@ -81,7 +81,7 @@ This time we'll enter the gene's ID, `Smp_124460`, into the search box and click
 "Open." You can also try searching for `ATPase` and see that there are two
 matches for that term. The one we're working on is the first match.
 
-![Text search](search-text.svg)
+![Text search](search-text.png)
 
 Somewhere to the side of the existing gene, click and drag an area in the ruler
 and then select "Add new feature". Look a the possible ontology types suggested,
@@ -90,4 +90,4 @@ choose the coordinates and "Match part" as the type.
 
 Now right-click on the "match" feature and select "Delete feature".
 
-![Add feature](add-feature.svg)
+![Add feature](add-feature.png)

packages/website/docusaurus.config.ts

@@ -101,7 +101,7 @@ const config: Config = {
     prism: {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
-      additionalLanguages: ['docker'],
+      additionalLanguages: ['docker', 'shell-session'],
     },
   } satisfies Preset.ThemeConfig,
 }