feat: add Neuroglancer short link docs

astro.config.mjs

@@ -47,6 +47,10 @@ export default defineConfig({
           items: [
             { label: "Navigating Files", slug: "workflows/navigation" },
             { label: "Creating Data Links", slug: "workflows/data-links" },
+            {
+              label: "Neuroglancer Short Links",
+              slug: "workflows/ng-links",
+            },
             {
               label: "File Conversion Requests",
               slug: "workflows/file-conversion",

src/content/docs/getting-started/quick-start.mdx

@@ -15,6 +15,8 @@ import lightZarrDataLink from '@assets/task-images/light-quick-start-zarr-data-l
 import darkZarrDataLink from '@assets/task-images/dark-quick-start-zarr-data-link.png'
 import lightZarrConversion from '@assets/task-images/light-zarr-conversion-request.png'
 import darkZarrConversion from '@assets/task-images/dark-zarr-conversion-request.png'
+import createNgLinkDark from '@assets/task-images/create-ng-link-dark.png'
+import createNgLinkLight from '@assets/task-images/create-ng-link-light.png'
 import mascot from '@assets/mascot/fg-starting-line.png'
 
 <img src={mascot.src} alt="Fileglancer mascot" style="width: 150px; float: right; margin: 0 0 1rem 1rem;" />
@@ -103,6 +105,38 @@ lightSrc={lightZarrDataLink}
 darkSrc={darkZarrDataLink}
 alt="Screenshot of the Fileglancer interface, with an arrow pointing to the 'navigate to path' button in the toolbar and to the Zarr viewer buttons under a Zarr thumbnail."
 />
+
+## Share a configured Neuroglancer view
+
+Once you have your image open in Neuroglancer (via a data link), you can save and share the exact viewer state (including layer visibility, colors, zoom level, and camera position) using Neuroglancer Short Links. This allows collaborators to see not just the image data, but your specific configuration of how to view it.
+
+<Steps>
+1. **Configure your view**<br/>
+With your image open in Neuroglancer, adjust the layers, colors, and camera position exactly how you want collaborators to see it.
+
+2. **Copy the Neuroglancer URL**<br/>
+From your Neuroglancer browser tab, copy the full URL from the address bar.
+
+3. **Navigate to NG Links page**<br/>
+In Fileglancer, click "NG Links" in the top navigation bar.
+
+4. **Create a new link**<br/>
+Click "+ New Link" button, select "URL Mode", paste your Neuroglancer URL, and optionally add a name and title.
+
+5. **Share the short link**<br/>
+Copy the generated short link and share it with your collaborators. They'll see exactly what you configured, and you can update the Neuroglancer state associated with the link later without changing the short link URL.
+</Steps>
+
+:::tip[Why use Neuroglancer short links?]
+Neuroglancer URLs can be very long and complex. The Neuroglancer short links created in Fileglancer are stable, shareable URLs that are easier to work with and can be updated without breaking existing links shared with collaborators.
+:::
+
+<StyledImage
+lightSrc={createNgLinkLight}
+darkSrc={createNgLinkDark}
+alt="Screenshot of the Fileglancer NG Links page, with an arrow pointing to the '+ New Link' button."
+/>
+
 ## Request a file conversion
 
 If your data is not already in OME-Zarr format, we can help!
@@ -158,7 +192,13 @@ alt="Screenshot of the Fileglancer interface, with an arrow pointing to the Conv
 3. Monitor the conversion progress on the *Tasks* page
 4. Once complete, create a data link for the converted data
 
-### Scenario 3: Organizing Your Workflow
+### Scenario 3: Collaborating on Image Analysis
+1. Open your OME-Zarr image in Neuroglancer
+2. Configure the viewer to highlight specific features or regions
+3. Create a Neuroglancer Short Link on the NG Links page
+4. Share the short link with collaborators so they see exactly what you configured
+
+### Scenario 4: Organizing Your Workflow
 1. Use search to find all your project directories
 2. Save frequently-accessed folders as favorites
 3. Create data links for datasets you reference often
@@ -170,6 +210,7 @@ Now that you've completed the basics, explore these guides for more detailed wor
 
 - **[Navigation Guide](../../workflows/navigation/)**: Master all navigation features
 - **[Data Links Guide](../../workflows/data-links/)**: Learn advanced sharing options
+- **[Neuroglancer Short Links Guide](../../workflows/ng-links/)**: Deep dive into creating and managing viewer state links
 - **[File Conversion Guide](../../workflows/file-conversion/)**: Understand the complete conversion process
 
 ## Quick Reference
@@ -180,7 +221,9 @@ Now that you've completed the basics, explore these guides for more detailed wor
 | Navigate to specific path | Toolbar widget | Paste path and navigate |
 | Save favorite | Toolbar | Click star icon |
 | Create data link | Properties Panel | Toggle switch in Overview |
+| Create Neuroglancer Short Link | NG Links page | Click "+ New Link" button |
 | Request conversion | Properties Panel | Use Conversion tab |
 | View all data links | URL | Navigate to the **Data Links** page |
+| View all Neuroglancer Short Links | URL | Navigate to the **NG Links** page |
 | Check data conversion task status | URL | Navigate to the **Tasks** page |
 | Go to home directory | Toolbar | Click home icon |

src/content/docs/index.mdx

@@ -51,7 +51,7 @@ alt="Screenshot of the Fileglancer interface showing a directory of OME-Zarr dat
 
 ## Common Workflows
 
-<CardGrid>
+<CardGrid stagger>
 	<Card title="Navigate Your Data" icon="right-arrow">
 		Learn how to browse files, save favorites, and efficiently navigate large directory structures.
 
@@ -62,6 +62,11 @@ alt="Screenshot of the Fileglancer interface showing a directory of OME-Zarr dat
 
 		[Data Links Guide →](./workflows/data-links/)
 	</Card>
+	<Card title="Create Neuroglancer Links" icon="star">
+		Save and share Neuroglancer views - your collaborators see exactly what you see.
+
+		[Neuroglancer Short Links Guide →](./workflows/ng-links/)
+	</Card>
 	<Card title="Request Conversions" icon="setting">
 		Submit requests for file format conversions and data processing through the integrated help desk system.
 

src/content/docs/workflows/ng-links.mdx

@@ -0,0 +1,265 @@
+---
+title: Neuroglancer Short Links
+description: Create and share persistent Neuroglancer viewer states to collaborate on image analysis.
+---
+
+import { Steps } from "@astrojs/starlight/components";
+import StyledImage from "@components/StyledImage.astro";
+import mascot from "@assets/mascot/fg-point-self.png";
+import createNgLinkLight from "@assets/task-images/create-ng-link-light.png";
+import createNgLinkDark from "@assets/task-images/create-ng-link-dark.png";
+import creatNgUrlDark from "@assets/task-images/create-ng-link-url-dark.png";
+import createNgUrlLight from "@assets/task-images/create-ng-link-url-light.png";
+import createNgStateDark from "@assets/task-images/create-ng-link-json-dark.png";
+import createNgStateLight from "@assets/task-images/create-ng-link-json-light.png";
+import ngActionsDark from "@assets/task-images/ng-link-actions-dark.png";
+import ngActionsLight from "@assets/task-images/ng-link-actions-light.png";
+import ngEditLinkDark from "@assets/task-images/ng-link-edit-url-dark.png";
+import ngEditLinkLight from "@assets/task-images/ng-link-edit-url-light.png";
+
+<img
+  src={mascot.src}
+  alt="Fileglancer mascot"
+  style="width: 150px; float: right; margin: 0 0 1rem 1rem;"
+/>
+
+Neuroglancer Short Links allow you to save and share specific Neuroglancer viewer states, including layer visibility, color settings, zoom levels, and camera positions. This makes it easy to collaborate with colleagues by pointing them to exactly what you want them to see in your imaging data.
+
+## What are Neuroglancer Short Links?
+
+- **Persistent viewer states**: Save your exact Neuroglancer configuration including visible layers, colors, and camera position
+- **Shareable URLs**: Generate short, stable links that can be shared with internal collaborators
+- **Updateable**: Edit the viewer state associated with an existing short link without changing the URL
+- **Collaboration-focused**: Ensure everyone sees exactly the same view of your data
+
+## Prerequisites
+
+Before creating Neuroglancer Short Links, you need:
+
+- A data link for your Zarr, OME-Zarr, or N5 image (see [Creating Data Links](/workflows/data-links/))
+- The image opened in Neuroglancer viewer
+
+## Creating a Neuroglancer Short Link
+
+### Step 1: Prepare Your Neuroglancer View
+
+<Steps>
+1. **Create a data link for your image**<br/>
+Navigate to your Zarr, OME-Zarr, or N5 directory and create a data link if one doesn't already exist.
+
+2. **Open in Neuroglancer**<br/>
+Click the Neuroglancer viewer icon under the image thumbnail to open your data in Neuroglancer.
+
+3. **Configure your view**<br/>
+Adjust the image to appear exactly as you want collaborators to see it.
+</Steps>
+
+### Step 2: Create the Short Link
+
+<StyledImage
+  lightSrc={createNgLinkLight}
+  darkSrc={createNgLinkDark}
+  alt="Screenshot of the Fileglancer NG Links page, with an arrow pointing to the '+ New Link' button."
+/>
+
+<Steps>
+1. **Navigate to the NG Links page**<br/>
+Return to Fileglancer and click "NG Links" in the top navigation bar.
+
+2. **Click "+ New Link" button**<br/>
+This opens the Create Neuroglancer Short Link dialog.
+
+3. **Choose your link mode**<br/>
+Select either URL Mode or State Mode depending on how you want to save your viewer state.
+</Steps>
+
+### URL Mode
+
+Use URL Mode to save the complete Neuroglancer URL with embedded state.
+
+<StyledImage
+  lightSrc={createNgUrlLight}
+  darkSrc={creatNgUrlDark}
+  alt="Screenshot of the Fileglancer Create Neuroglancer Short Link dialog, with the URL Mode option selected."
+/>
+
+<Steps>
+1. **Copy the Neuroglancer URL**<br/>
+From your Neuroglancer browser tab, copy the full URL from the address bar. This URL contains all your viewer settings encoded in the URL parameters.
+
+2. **Paste into the Neuroglancer URL field**<br/>
+Paste the complete URL into the dialog.
+
+3. **Add optional metadata**<br/>
+**Title** (optional): Appears in the Neuroglancer browser tab when the link is opened
+**Name** (optional): Appears in the NG Links table for easy identification. If not provided, a random key will be used as the name.
+
+4. **Click "Create"**<br/>
+Your short link will be generated and added to the NG Links table.
+</Steps>
+
+### State Mode
+
+Use State Mode when you want to save just the JSON state separately from the base URL.
+
+<StyledImage
+  lightSrc={createNgStateLight}
+  darkSrc={createNgStateDark}
+  alt="Screenshot of the Fileglancer Create Neuroglancer Short Link dialog, with the State Mode option selected."
+/>
+
+<Steps>
+1. **Copy the JSON state from Neuroglancer**<br/>
+In Neuroglancer, access the JSON state (typically through the state sharing dialog or browser console).
+
+2. **Paste into the JSON State field**<br/>
+Paste the JSON state object into the large text area.
+
+3. **Verify the Neuroglancer Base URL**<br/>
+Check that the base URL field contains the correct Neuroglancer instance URL. Adjust if necessary (e.g., `https://neuroglancer-demo.appspot.com/`).
+
+4. **Add optional metadata**<br/>
+**Title** (optional): Appears in the Neuroglancer browser tab
+**Name** (optional): Appears in the NG Links table for identification
+
+5. **Click "Create"**<br/>
+Your short link will be generated and added to the NG Links table.
+</Steps>
+
+## Managing Your Neuroglancer Short Links
+
+### Viewing All Links
+
+All your Neuroglancer Short Links appear in a table on the NG Links page. The table displays:
+
+- **Name**: The custom name you provided, or the auto-generated key
+- **Neuroglancer Short Link**: The shortened URL that opens the viewer
+- **Date Created**: When the link was created
+- **Key**: The unique identifier for this link
+- **Actions**: Options menu for managing the link
+
+### Opening a Link in Neuroglancer
+
+<Steps>
+  1. **Click the Neuroglancer Short Link**<br />
+  In the table, click on the blue link in the "Neuroglancer Short Link" column
+  to open the viewer in a new tab.
+</Steps>
+
+### Sharing with Collaborators
+
+<StyledImage
+  lightSrc={ngActionsLight}
+  darkSrc={ngActionsDark}
+  alt="Screenshot of the Fileglancer NG Links page, with an arrow pointing to the Actions button on a link row."
+/>
+
+<Steps>
+1. **Click the Actions button**<br/>
+On the right side of the table row for your link.
+
+2. **Select "Copy Neuroglancer Link"**<br/>
+   The shortened URL is copied to your clipboard.
+
+3. **Share the link**<br/>
+   Send the link to your collaborators. Anyone with access to the Janelia network can use the link to see exactly what you configured in Neuroglancer.
+
+   :::note[Sharing with external collaborators]
+   If your image data is located in a `data_external` folder on a Janelia file share, the Neuroglancer Short Link can be viewed outside the Janelia network. Files in `data_external` folders are automatically made public on [s3.janelia.org](https://s3.janelia.org).
+   :::
+
+4. **Alternative: Copy JSON state link**<br/>
+   You can also select "Copy JSON state link" from the actions menu to share a link to just the state data.
+</Steps>
+
+### Updating an Existing Link
+
+<StyledImage
+  lightSrc={ngEditLinkLight}
+  darkSrc={ngEditLinkDark}
+  alt="Screenshot of the Fileglancer NG Links page with the Edit dialog open."
+/>
+
+If you need to update the viewer state for an existing short link:
+
+<Steps>
+1. **Make changes in Neuroglancer**<br/>
+Open your link in Neuroglancer and adjust the view as needed.
+
+2. **Click the Actions button**<br/>
+   On the right side of the table row for your link.
+
+3. **Select "Edit"**<br/>
+   This opens the Edit Neuroglancer Short Link dialog.
+
+4. **Update the state**<br/>
+   In **URL Mode**: Paste the new Neuroglancer URL<br/>
+   In **State Mode**: Paste the updated JSON state and verify the base URL
+
+5. **Update the title if needed**<br/>
+   Optionally modify the title that appears in the browser tab.
+
+6. **Click "Save"**<br/>
+   The same short link URL will now point to your updated viewer state. Collaborators using the original link will automatically see the new configuration.
+</Steps>
+
+### Deleting a Link
+
+<Steps>
+1. **Click the Actions button**<br/>
+On the right side of the table row for your link.
+
+2. **Select "Delete"**<br/>
+   Confirm the deletion in the dialog that appears.
+
+3. **Link is revoked**<br/>
+   The short link will immediately stop working. Anyone with the link will no longer be able to access the viewer state.
+</Steps>
+
+## Troubleshooting
+
+### Link doesn't open in Neuroglancer
+
+**Problem**: Clicking the short link returns an error or doesn't load the viewer
+
+**Solutions**:
+
+- Verify you're on the Janelia network
+- Check that the underlying data link is still active (visit the [Data Links](/workflows/data-links/) page)
+- Ensure the source data hasn't been moved or deleted
+- Try copying the link and opening it in a new browser tab
+
+### Can't create a new link
+
+**Problem**: The "+ New Link" button doesn't work or the dialog won't submit
+
+**Solutions**:
+
+- Verify you have a valid Neuroglancer URL or JSON state to paste
+- Check that your session is still authenticated (try refreshing the page)
+- Ensure the JSON state is valid JSON format (use a JSON validator if needed)
+
+### Collaborators can't access the link
+
+**Problem**: Others report that the link doesn't work for them
+
+**Solutions**:
+
+- Confirm they're on the Janelia internal network
+- Verify the link is still active in your NG Links table
+- Check that the underlying data link is still active (visit the [Data Links](/workflows/data-links/) page)
+- Try copying and resharing the link in case of clipboard issues
+
+## Best Practices
+
+- **Use descriptive names**: Give your links meaningful names so you can easily find them later
+- **Add titles**: Include descriptive titles so collaborators know what they're viewing when they open the link
+- **Document your links**: Keep notes about what each link demonstrates, especially if you have many links
+- **Clean up old links**: Regularly review your NG Links table and delete links that are no longer needed
+- **Test before sharing**: Always open your link yourself before sending it to others to ensure it works as expected
+- **Maintain data links**: Remember that Neuroglancer Short Links depend on the underlying data links being active
+
+## Related Features
+
+- [Creating Data Links](/workflows/data-links/) - Learn how to create the data links needed for Neuroglancer Short Links
+- [Navigating Files](/workflows/navigation/) - Find and browse your imaging data in Fileglancer