ome · lubianat · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/.github/workflows/html-proofer.yml b/.github/workflows/html-proofer.yml
@@ -0,0 +1,62 @@
+name: "Build and Lint Site"
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "specifications/**"
+      - "rfc/**"
+      - "resources/**"
+      - "community/**"
+      - "contributing/**"
+      - "help-desk/**"
+      - "_html_extra/**"
+      - "_static/**"
+      - "_ext/**"
+      - "images/**"
+      - "**/*.md"
+      - "conf.py"
+      - "requirements.txt"
+      - "readthedocs.yml"
+      - ".github/workflows/build-lint.yml"
+
+concurrency:
+  group: build-lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-site:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      # dependencies
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install specifications/dev
+          gem install html-proofer
+
+      - name: Build the site
+        run: sphinx-build -b html . _build/html
+
+      - name: Validate all links, enforce alt text
+        run: htmlproofer --ignore-files "/.*\/specifications\/(0\.[0-9]+|dev)\/.*/,/.*webpack-macros\.html/,/.*\/rfc\/4\/markdown\/.*/,/.*\/rfc\/5\/.*/,/.*\/rfc\/1\/.*/,/.*\/0\.[0-9]+(\.html|\/.*)/" --disable-external ./_build/html
+
+      - name: Ensure no unexpected encoded HTML in output
+        run: |
+          ! fgrep -R 'lt;blockquote' _build/html
diff --git a/README.md b/README.md
@@ -14,16 +14,9 @@ See also [CONTRIBUTING.md](./contributing/index.md)
 
 Specifications have been moved to [ome/ngff-spec](https://github.com/ome/ngff-spec).
 
-### Editing specifications
-
-Specifications are written in markdown, or technically
-[bikeshed](https://github.com/tabatkins/bikeshed) -- a markdown document, with
-special extensions understood by the bikeshed tool. The bikeshed tool is run
-during the Sphinx build step (see conf.py).
-
 # RFCs
 
-Requests for comments (RFCs) are used to discuss and capture high-level decisions within the NGFF community. 
+Requests for comments (RFCs) are used to discuss and capture high-level decisions within the NGFF community.
 
 RFCs are contained under the `rfc` directory at the moment but may be moved out into a separate repo in the future.
 
@@ -37,5 +30,3 @@ RFCs are contained under the `rfc` directory at the moment but may be moved out
 <!-- prettier-ignore-end -->
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
-
-
diff --git a/boilerplate/header.include b/boilerplate/header.include
@@ -10,7 +10,7 @@
 <body class="h-entry">
 <div class="head">
 
-  <img src="http://www.openmicroscopy.org/img/logos/ome-logomark.svg" alt="OME logo (6 circles in a hexagon)" style="float:right;width:42px;height:42px;">
+  <img src="https://www.openmicroscopy.org/img/logos/ome-logomark.svg" alt="OME logo (6 circles in a hexagon)" style="float:right;width:42px;height:42px;">
 
   <h1 id="title" class="p-name no-ref">[TITLE]</h1>
   <h2 id="subtitle" class="no-num no-toc no-ref">[LONGSTATUS],

diff --git a/contributing/specification/index.md b/contributing/specification/index.md
@@ -6,14 +6,14 @@ request for comment (RFC) documents.
 
 In the future we will flesh out this page with a guide to RFCs, but in the
 meantime the RFC process is outlined in the
-[Implementation section of RFC 1](../rfc/1/index.md#implementation).
+[Implementation section of RFC 1](rfc1-implementation).
 
 ## Comment on a Request For Comment (RFC)
 
 If you want to leave a suggestion or comment on an RFC that is under review,
 please leave a comment in a new page under the "comments/" directory for the
 relevant RFC. A template is also available for formatting your comment:
-[template](../rfc/1/templates/review_template).
+[template](rfc1-review-template).
 
 ## How to change the specification
 
@@ -143,7 +143,7 @@ Other useful admonitions and directives (e.g., `hint`, `note`) can be found [her
 
 ## Building *only* the spec document
 
-The spec document under the [ngff-spec](github.com/ome/ngff-spec) repository can be built as a standalone document to make writing and rendering a smoother experience.
+The spec document under the [ngff-spec](https://github.com/ome/ngff-spec) repository can be built as a standalone document to make writing and rendering a smoother experience.
 To build the spec document, you first need to install the necessary dependencies:
 
 After cloning the ngff-spec repo, navigate into the repository on your machine and install the dependencies using pip:

diff --git a/help-desk/index.md b/help-desk/index.md
@@ -1,8 +1,8 @@
 # Help Desk
 
-* [Glossary](#glossary)
-* [FAQs](#faqs)
-* [Where to seek for help](#where-to-seek-for-help)
+- [Glossary](#glossary)
+- [FAQs](#faqs)
+- [Where to seek for help](#where-to-seek-for-help)
 
 ## Glossary
 
@@ -29,31 +29,56 @@ Jump to:
 
 [Back to top](#glossary)
 
+### D
+
+[Back to top](#glossary)
+
+### E
+
+[Back to top](#glossary)
+
+### F
+
+[Back to top](#glossary)
+
 ### G
 
 [Back to top](#glossary)
 
-### H 
+### H
 
 **HCS** - Dedicated layout of OME-Zarr files representing the used wells and plates for High Content Screening (HCS). The layout allows a user to efficiently address and analyze specific data from specific wells.
 
 **HDF5** - Hierarchical Data Format version 5 (HDF5). It is a data model, file format, and library for organizing, storing, and managing large and complex data.
 
 [Back to top](#glossary)
 
+### I
+
+[Back to top](#glossary)
+
 ### J
 
 **JSON file** - A simple standardized human-readable data format for sharing data using nested key-value pairs.
 
 [Back to top](#glossary)
 
+### K
+
+[Back to top](#glossary)
+
+### L
+
+[Back to top](#glossary)
+
 ### M
 
 **Multiscale** - Multiscale means storing the same image at multiple resolutions (full size, half size, quarter size, etc.). This makes it easy for tools to zoom and navigate very large images quickly—just like how map apps load lower-resolution versions first, then sharpen the view as you zoom in.
 
 [Back to top](#glossary)
 
 ### N
+
 **NGFF** - Next Generation File Format (NGFF) is a community for solving problems related to producing open-source software for microscopy data.
 
 [Back to top](#glossary)
@@ -66,7 +91,7 @@ Jump to:
 
 **OME-NGFF** - OME-NGFF refers to the resulting efforts of the OME & NGFF communities.
 
-**OME-Zarr** - An OME-Zarr is a standardized file format for microscopy images. More details on the [main page](#../).
+**OME-Zarr** - An OME-Zarr is a standardized file format for microscopy images. More details on the [main page](#main-page).
 
 [Back to top](#glossary)
 
@@ -76,6 +101,10 @@ Jump to:
 
 [Back to top](#glossary)
 
+### Q
+
+[Back to top](#glossary)
+
 ### R
 
 **RFC** - Request For Comments (RFC) is a process for proposing a change to the standardized specification for OME-Zarr files.
@@ -84,7 +113,7 @@ Jump to:
 
 ### S
 
-**Shard/ing** - Like [Chunks](#c), sharding is a way of breaking up pixel data for more efficient access. Shards are groups of chunks with headers in front of them for describing the chunks inside.
+**Shard/ing** - Like [Chunks](#c), sharding is a way of breaking up pixel data for more efficient access. Shards are groups of chunks in a single object with headers describing the chunks inside.
 
 [Back to top](#glossary)
 
@@ -96,6 +125,9 @@ Jump to:
 
 ### U
 
+[Back to top](#glossary)
+
+### V
 
 [Back to top](#glossary)
 
@@ -105,9 +137,17 @@ Jump to:
 
 [Back to top](#glossary)
 
+### X
+
+[Back to top](#glossary)
+
+### Y
+
+[Back to top](#glossary)
+
 ### Z
 
-**Zarr** -- A file format, see the [main page](#../) for more information about what a Zarr is and the benefits of using Zarr.
+**Zarr** -- A file format, see the [main page](#main-page) for more information about what a Zarr is and the benefits of using Zarr.
 
 **Zarr Group** - A Zarr group is like a folder inside a dataset. It can hold arrays, metadata, or other groups, helping organize complex data into a clear hierarchy. Think of it as a way to keep all related images and information neatly together.
 
@@ -172,15 +212,14 @@ That is often the case. OME-Zarr include multiresolution data (i.e. pyramids), w
 
 Not yet fully. Some workarounds are possible (1D arrays, mesh formats), but this is an active area of development.
 
-
-
+(where-to-seek-for-help)=
 ## Where to look for help
+
 If you have questions or need help with OME-Zarr, you can reach out through the following channels:
-| Where | Description | When to use  |
+| Where | Description | When to use |
 |-------|-------------| --------------|
-| [Image.sc Forum](https://forum.image.sc) | A community forum for image analysis and bioimaging. | To know when to use the tags [ngff](https://forum.image.sc/tag/ngff), [ome-ngff](https://forum.image.sc/tag/ome-ngff),  and [ome-zarr](https://forum.image.sc/tag/ome-zarr) in the forum please read [Landing Page](https://ngff.openmicroscopy.org/index.html), Glossary and FAQs in this page. |
+| [Image.sc Forum](https://forum.image.sc) | A community forum for image analysis and bioimaging. | To know when to use the tags [ngff](https://forum.image.sc/tag/ngff), [ome-ngff](https://forum.image.sc/tag/ome-ngff), and [ome-zarr](https://forum.image.sc/tag/ome-zarr) in the forum please read [Landing Page](https://ngff.openmicroscopy.org/index.html), Glossary and FAQs in this page. |
 | [ome/ngff GitHub Issues](https://github.com/ome/ngff/issues) | The official repository for OME-NGFF specifications and related discussions. | For reporting bugs, suggesting features, or discussing technical aspects of the OME-NGFF specifications. |
 | Office Hours | Regularly scheduled virtual meetings where you can ask questions and get help from the NGFF community | Office hours rotate between APAC/AU/EU- and AMER/AU/EU-friendly times. Join them when you want to chat about OME-Zarr. Read more in the [Community](../community/index.md) page. |
 | OME-Zarr libraries GitHub Issues| Various repositories for OME-Zarr libraries. | For issues specific to a particular OME-Zarr library, use the respective GitHub repository's issue. |
 | In person events | Conferences, workshops, and meetups where you can connect with the NGFF community. | To network, learn, and discuss OME-Zarr in person. Check the [Community](../community/index.md) page for upcoming events. |
-
diff --git a/index.md b/index.md
@@ -1,3 +1,4 @@
+(main-page)=
 # Next-Generation File Formats (NGFF) + OME-Zarr
 
 Welcome to the Next-Generation File Formats (NGFF) main page! This site is dedicated to providing resources for the NGFF community and those that are interested in getting started with OME-Zarr.
@@ -15,63 +16,63 @@ In summary, OME-Zarr allows you to store, share and stream large images. You can
 An OME-Zarr is a file format optimized for storing, viewing, & sharing large images.
 There are two parts to an OME-Zarr:
 
-* **The "Zarr" part describes how the pixel data for the images are laid out**
-* **The "OME" part, which stands for [Open Microscopy Environment](https://www.openmicroscopy.org/), describes metadata about the pixel data. This includes metadata such as:
-  * spatial relationships
-  * high content screening data
-  * well data
-  * [and more](./specifications/index)!
+- **The "Zarr" part describes how the pixel data for the images are laid out**. [Zarr](https://zarr.dev) is a next-generation data format used for scientific datasets in multiple domains.
+- **The "OME" part describes metadata about the pixel data.** OME stands for [Open Microscopy Environment](https://www.openmicroscopy.org/). This includes metadata such as:
+  - spatial relationships
+  - high content screening data
+  - well data
+  - [and more](./specifications/index)!
 
 ## Why would I use OME-Zarr?
 
 In general, OME-Zarr is growing as a default [FAIR](https://en.wikipedia.org/wiki/FAIR_data) choice for storing and sharing microscopy images.
 
 OME-Zarr files have two major benefits:
 
-* **Standardization:** "OME-Zarr" is a "Zarr" with embedded standardized metadata in the Open Microscopy Environment (OME) format.
-  * **_Sharing_**: It eases cross-organization file sharing, aiding organizational collaboration and data sharing. Repositories like the [Image Data Resource](https://idr.openmicroscopy.org/) and [BioImage Archive](https://www.ebi.ac.uk/bioimage-archive/) are currently migrating to having OME-Zarr as a standard format for _all_ their data.
-  * **_Interoperability_**: Standardized metadata enables the ability to "mix and match" tools from different organizations, benefiting from the strengths of multiple tools as needed.
+- **Standardization:** "OME-Zarr" is a "Zarr" with embedded standardized metadata in the Open Microscopy Environment (OME) format.
+  - **_Sharing_**: It eases cross-organization file sharing, aiding organizational collaboration and data sharing. Repositories like the [Image Data Resource](https://idr.openmicroscopy.org/) and [BioImage Archive](https://www.ebi.ac.uk/bioimage-archive/) are currently migrating to having OME-Zarr as a standard format for _all_ their data.
+  - **_Interoperability_**: Standardized metadata enables the ability to "mix and match" tools from different organizations, benefiting from the strengths of multiple tools as needed.
 
-* **Parallel access**: Chunking is inherent to "Zarr" files. This means "Zarr" files are stored in independently-accessible blocks.
-  * **_Storage_**: Microscopy images can be quite large and can therefore reach Cloud system storage limits for individual files; the chunked nature of a Zarr can alleviate this issue. Some storage systems may also duplicate byte-equivalent files, so a chunked file like Zarr may save storage space.
-  * **_Viewing_**: Viewers can target specific chunks to load based upon the current view, reducing lag, & enabling massive images to be viewed within browsers.
-  * **_Cost_**: When viewing or reading data, the total cost of accessing a Zarr file on the cloud may be less than a more monolithic file format due to the more efficient data access patterns. Ex. A viewer can just access the chunks of the image it needs to display rather than the entire image.
+- **Parallel access**: Chunking is inherent to "Zarr" files. This means "Zarr" files are stored in independently-accessible blocks.
+  - **_Storage_**: Microscopy images can be quite large and can therefore reach Cloud system storage limits for individual files; the chunked nature of a Zarr can alleviate this issue. Some storage systems may also duplicate byte-equivalent files, so a chunked file like Zarr may save storage space.
+  - **_Viewing_**: Viewers can target specific chunks to load based upon the current view, reducing lag, & enabling massive images to be viewed within browsers.
+  - **_Cost_**: When viewing or reading data, the total cost of accessing a Zarr file on the cloud may be less than a more monolithic file format due to the more efficient data access patterns. Ex. A viewer can just access the chunks of the image it needs to display rather than the entire image.
 
 Of note, both benefits contribute to **_AI-readiness_**: the standardized metadata & access patterns provide a common layer for machine-learning workflows, reducing the friction for developers to build and test models.
 
-The [tools](./tools/index), [data](./data/index), and [ecosystem](./ecosystem/index) may provide a better sense of the range of scientific use cases that may benefit from OME-Zarr. The [publications](./publications/index) page provides a list of publications that have used OME-Zarr in their work.
+The [tools](#resources-tools), [data](#resources-data), and [ecosystem](#resources-ecosystem) may provide a better sense of the range of scientific use cases that may benefit from OME-Zarr. The [publications](#resources-publications) page provides a list of publications that have used OME-Zarr in their work.
 
 ## When would I not use OME-Zarr?
 
 While the format matures, it may be frustrating to use OME-Zarr in some cases, for example:
 
-* If you are working with small images, not planning to share them and your current tools already work well, then using OME-Zarr may not be necessary. Planned expansions to the specification (such as single-file Zarrs) will make it more convenient in these scenarios.
+- If you are working with small images, not planning to share them and your current tools already work well, then using OME-Zarr may not be necessary. Planned expansions to the specification (such as single-file Zarrs) will make it more convenient in these scenarios.
 
-* If you need specific conditions for which OME-Zarr support is not mature, you may need to use a different file format.
-  * Particularly, if your original file is lossy compressed, you will see a large increase in file size (about an order of magnitude) as the images are decompressed into OME-Zarr, since transferring lossy compressed tiles is not yet supported. This currently impacts most whole slide image (WSI) formats such as SVS, CZI, and NDPI, which are lossy JPEG compressed by default.
+- If you need specific conditions for which OME-Zarr support is not mature, you may need to use a different file format.
+  - Particularly, if your original file is lossy compressed, you will see a large increase in file size (about an order of magnitude) as the images are decompressed into OME-Zarr, since transferring lossy compressed tiles is not yet supported. This currently impacts most whole slide image (WSI) formats such as SVS, CZI, and NDPI, which are lossy JPEG compressed by default.
 
 ## Who is using OME-Zarr?
 
 These are _some_ of the organizations (and their dataset pages) that are using OME-Zarr for their data.
 
-* [Allen Institute](https://bff.allencell.org/datasets)
-* biohub
-* [Broad Institute](https://broadinstitute.github.io/cellpainting-gallery/overview.html)
-* [EMBL - Image Data Resource (IDR)](https://idr.openmicroscopy.org/)
-* [Howard Hughes Medical Institute, Janelia (HHMI)](https://openorganelle.janelia.org/)
-* [Jackson Laboratory (JAX)](https://images.jax.org/)
-* ... [and more](./data/index)
+- [Allen Institute](https://bff.allencell.org/datasets)
+- biohub
+- [Broad Institute](https://broadinstitute.github.io/cellpainting-gallery/overview.html)
+- [EMBL - Image Data Resource (IDR)](https://idr.openmicroscopy.org/)
+- [Howard Hughes Medical Institute, Janelia (HHMI)](https://openorganelle.janelia.org/)
+- [Jackson Laboratory (JAX)](https://images.jax.org/)
+- ... [and more](#resources-data)
 
 ## How do I use OME-Zarr?
 
-* Already have a Zarr?
-  * Check out the [tools section](./tools/index)!
-* Want to create a Zarr?
-  * Check out the [tools section](./tools/index)!
-* Want to see or download a Zarr?
-  * Check out the [data section](./data/index)!
-* Want to cite OME-Zarr/NGFF in your work?
-  * Check out the [publications section](./publications/index)!
+- Already have a Zarr?
+  - Check out the [tools section](#resources-tools)!
+- Want to create a Zarr?
+  - Check out the [tools section](#resources-tools)!
+- Want to see or download a Zarr?
+  - Check out the [data section](#resources-data)!
+- Want to cite OME-Zarr/NGFF in your work?
+  - Check out the [publications section](#resources-publications)!
 
 ## Have other questions?