Restructured references section of the docs

docs/source/reference/api-reference/app.md

@@ -0,0 +1,13 @@
+# Application configuration
+
+## Module: {mod}`jupyterhub.app`
+
+```{eval-rst}
+.. automodule:: jupyterhub.app
+```
+
+### {class}`JupyterHub`
+
+```{eval-rst}
+.. autoconfigurable:: JupyterHub
+```

docs/source/reference/api-reference/auth.md

@@ -0,0 +1,33 @@
+# Authenticators
+
+## Module: {mod}`jupyterhub.auth`
+
+```{eval-rst}
+.. automodule:: jupyterhub.auth
+```
+
+### {class}`Authenticator`
+
+```{eval-rst}
+.. autoconfigurable:: Authenticator
+   :members:
+```
+
+### {class}`LocalAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: LocalAuthenticator
+   :members:
+```
+
+### {class}`PAMAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: PAMAuthenticator
+```
+
+### {class}`DummyAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: DummyAuthenticator
+```

docs/source/reference/api-reference/proxy.md

@@ -0,0 +1,21 @@
+# Proxies
+
+## Module: {mod}`jupyterhub.proxy`
+
+```{eval-rst}
+.. automodule:: jupyterhub.proxy
+```
+
+### {class}`Proxy`
+
+```{eval-rst}
+.. autoconfigurable:: Proxy
+   :members:
+```
+
+### {class}`ConfigurableHTTPProxy`
+
+```{eval-rst}
+.. autoconfigurable:: ConfigurableHTTPProxy
+   :members: debug, auth_token, check_running_interval, api_url, command
+```

docs/source/reference/api-reference/service.md

@@ -0,0 +1,14 @@
+# Services
+
+## Module: {mod}`jupyterhub.services.service`
+
+```{eval-rst}
+.. automodule:: jupyterhub.services.service
+```
+
+### {class}`Service`
+
+```{eval-rst}
+.. autoconfigurable:: Service
+   :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec
+```

docs/source/reference/api-reference/services.auth.md

@@ -0,0 +1,40 @@
+# Services Authentication
+
+## Module: {mod}`jupyterhub.services.auth`
+
+```{eval-rst}
+.. automodule:: jupyterhub.services.auth
+```
+
+### {class}`HubAuth`
+
+```{eval-rst}
+.. autoconfigurable:: HubAuth
+   :members:
+```
+
+### {class}`HubOAuth`
+
+```{eval-rst}
+.. autoconfigurable:: HubOAuth
+   :members:
+```
+
+### {class}`HubAuthenticated`
+
+```{eval-rst}
+.. autoclass:: HubAuthenticated
+   :members:
+```
+
+### {class}`HubOAuthenticated`
+
+```{eval-rst}
+.. autoclass:: HubOAuthenticated
+```
+
+### {class}`HubOAuthCallbackHandler`
+
+```{eval-rst}
+.. autoclass:: HubOAuthCallbackHandler
+```

docs/source/reference/api-reference/spawner.md

@@ -0,0 +1,20 @@
+# Spawners
+
+## Module: {mod}`jupyterhub.spawner`
+
+```{eval-rst}
+.. automodule:: jupyterhub.spawner
+```
+
+### {class}`Spawner`
+
+```{eval-rst}
+.. autoconfigurable:: Spawner
+   :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
+```
+
+### {class}`LocalProcessSpawner`
+
+```{eval-rst}
+.. autoconfigurable:: LocalProcessSpawner
+```

docs/source/reference/api-reference/user.md

@@ -0,0 +1,34 @@
+# Users
+
+## Module: {mod}`jupyterhub.user`
+
+```{eval-rst}
+.. automodule:: jupyterhub.user
+```
+
+### {class}`UserDict`
+
+```{eval-rst}
+.. autoclass:: UserDict
+   :members:
+```
+
+### {class}`User`
+
+```{eval-rst}
+.. autoclass:: User
+   :members: escaped_name
+
+   .. attribute:: name
+
+      The user's name
+
+   .. attribute:: server
+
+      The user's Server data object if running, None otherwise.
+      Has ``ip``, ``port`` attributes.
+
+   .. attribute:: spawner
+
+      The user's :class:`~.Spawner` instance.
+```

docs/source/reference/index.md

@@ -1,20 +1,116 @@
 (reference-index)=
 
-# Technical Reference
+# Reference
+_Reference_ documentation provide technical descriptions about JupyterHub and how it works. 
+This section is divided into two broad subsections: 
+1. Technical reference.
+2. API reference.  
+---
+## Technical reference
 
 This section covers more of the details of the JupyterHub architecture, as well as
 what happens under-the-hood when you deploy and configure your JupyterHub.
 
-```{toctree}
-:maxdepth: 2
+### Technical overview
+Provides an overview of JupyterHub's components and how they work. 
 
-technical-overview
-urls
-authenticators
-spawners
-services
-rest-api
-monitoring
-../events/index
-config-reference
+```{toctree}
+:maxdepth: 1
+
+technical-reference/technical-overview
 ```
+
+### Subsystems
+
+Find details about the different JupyterHub subsystems. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/subsystems/authenticators
+technical-reference/subsystems/spawners
+```
+
+### Configuration
+
+Find useful information about configuring JupyterHub. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/configuration/config-reference
+technical-reference/configuration/services
+technical-reference/configuration/urls
+```
+
+### Events
+
+Find details about JupyterHub events and how to log them. 
+```{toctree}
+:maxdepth: 1
+
+../events/index
+```
+
+### Monitoring
+
+Find details about monitoring your JupyterHub deployment. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/monitoring/monitoring
+```
+
+### Deployments
+
+Find details about the institutions presently using JupyterHub. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/deployments/gallery-jhub-deployments
+```
+
+### Changelog
+
+Find details about changes to JupyterHub and its various releases.
+
+```{toctree}
+:maxdepth: 1
+
+technical-reference/changelog/changelog
+```
+---
+(api-index)=
+
+## API reference
+
+<!--
+    Below is a MyST field list, using MyST substitution, as supported
+    by enabling the respective MyST extensions in docs/source/conf.py.
+-->
+
+:Date: {{ date }}
+:Release: {{ version }}
+
+JupyterHub also provides a REST API for administration of the Hub and users.
+The documentation on [Using JupyterHub's REST API](using-jupyterhub-rest-api) provides
+information on:
+
+- what you can do with the API
+- creating an API token
+- adding API tokens to the config files
+- making an API request programmatically using the requests library
+- learning more about JupyterHub's API
+
+```{toctree}
+:maxdepth: 1
+
+rest-api
+api-reference/app
+api-reference/auth
+api-reference/spawner
+api-reference/proxy
+api-reference/user
+api-reference/service
+api-reference/services.auth
+```
+
+[openapi initiative]: https://www.openapis.org/

docs/source/reference/rest-api.md

@@ -1,3 +1,6 @@
+<!---
+This doc is part of the API references section of the References documentation.  
+--->
 (jupyterhub-rest-API)=
 
 # JupyterHub REST API

docs/source/reference/technical-reference/configuration/services.md

@@ -290,7 +290,7 @@ service. See the `service-whoami-flask` example in the
 [JupyterHub GitHub repo](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-whoami-flask)
 for more details.
 
-```{literalinclude} ../../../examples/service-whoami-flask/whoami-flask.py
+```{literalinclude} ../../../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
 :language: python
 ```
 
@@ -352,7 +352,7 @@ You will only get to this stage if the user has the required `access:services!se
 To retrieve the user model for the token, make a request to `GET /hub/api/user` with the token in the Authorization header.
 For example, using flask:
 
-```{literalinclude} ../../../examples/service-whoami-flask/whoami-flask.py
+```{literalinclude} ../../../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
 :language: python
 ```
 

docs/source/reference/technical-reference/configuration/urls.md

@@ -53,7 +53,7 @@ c.JupyterHub.default_url = '/services/my-landing-service'
 
 ## `/hub/home`
 
-![The Hub home page with named servers enabled](../images/named-servers-home.png)
+![The Hub home page with named servers enabled](/images/named-servers-home.png)
 
 By default, the Hub home page has just one or two buttons
 for starting and stopping the user's server.
@@ -70,14 +70,14 @@ If you have a form-based username+password login,
 such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module),
 this page will render the login form.
 
-![A login form](../images/login-form.png)
+![A login form](/images/login-form.png)
 
 If login is handled by an external service,
 e.g. with OAuth, this page will have a button,
 declaring "Log in with ..." which users can click
 to log in with the chosen service.
 
-![A login redirect button](../images/login-button.png)
+![A login redirect button](/images/login-button.png)
 
 If you want to skip the user interaction and initiate login
 via the button, you can set:
@@ -145,7 +145,7 @@ If something is really wrong, this can result in a redirect loop.
 Visiting this page will never result in triggering the spawn of servers
 without additional user action (i.e. clicking the link on the page).
 
-![Visiting a URL for a server that's not running](../images/not-running.png)
+![Visiting a URL for a server that's not running](/images/not-running.png)
 
 _Version changed: 1.0_
 
@@ -204,7 +204,7 @@ If `Spawner.options_form` is used,
 this will render a form,
 and a POST request will trigger the actual spawn and redirect.
 
-![The spawn form](../images/spawn-form.png)
+![The spawn form](/images/spawn-form.png)
 
 _Version added: 1.0_
 
@@ -218,7 +218,7 @@ which was responsible for triggering spawn and rendering progress, etc.
 
 ### `/hub/spawn-pending[/:username[/:servername]]`
 
-![The spawn pending page](../images/spawn-pending.png)
+![The spawn pending page](/images/spawn-pending.png)
 
 _Version added: 1.0_ this URL is new in JupyterHub 1.0.
 
@@ -236,7 +236,7 @@ and the page will show a link back to `/hub/spawn/...`.
 
 ## `/hub/token`
 
-![The token management page](../images/token-page.png)
+![The token management page](/images/token-page.png)
 
 On this page, users can manage their JupyterHub API tokens.
 They can revoke access and request new tokens for writing scripts
@@ -244,7 +244,7 @@ against the [JupyterHub REST API](using-jupyterhub-rest-api).
 
 ## `/hub/admin`
 
-![The admin panel](../images/named-servers-admin.png)
+![The admin panel](/images/named-servers-admin.png)
 
 Administrators can take various administrative actions from this page:
 

docs/source/reference/technical-reference/deployments/gallery-jhub-deployments.md

@@ -0,0 +1,195 @@
+(gallery-of-deployments)=
+
+# A Gallery of JupyterHub Deployments
+
+**A JupyterHub Community Resource**
+
+We've compiled this list of JupyterHub deployments to help the community
+see the breadth and growth of JupyterHub's use in education, research, and
+high performance computing.
+
+Please submit pull requests to update information or to add new institutions or uses.
+
+## Academic Institutions, Research Labs, and Supercomputer Centers
+
+### University of California Berkeley
+
+- [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/)
+
+  - [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
+
+- [Data 8](http://data8.org/)
+
+  - [GitHub organization](https://github.com/data-8)
+
+- [NERSC](https://www.nersc.gov/)
+
+  - [Press release on Jupyter and Cori](https://www.nersc.gov/news-publications/nersc-news/nersc-center-news/2016/jupyter-notebooks-will-open-up-new-possibilities-on-nerscs-cori-supercomputer/)
+  - [Moving and sharing data](https://www.nersc.gov/assets/Uploads/03-MovingAndSharingData-Cholia.pdf)
+
+- [Research IT](https://research-it.berkeley.edu)
+  - [JupyterHub server supports campus research computation](https://research-it.berkeley.edu/blog/17/01/24/free-fully-loaded-jupyterhub-server-supports-campus-research-computation)
+
+### University of California Davis
+
+- [Spinning up multiple Jupyter Notebooks on AWS for a tutorial](https://github.com/mblmicdiv/course2017/blob/HEAD/exercises/sourmash-setup.md)
+
+Although not technically a JupyterHub deployment, this tutorial setup
+may be helpful to others in the Jupyter community.
+
+Thank you C. Titus Brown for sharing this with the Software Carpentry
+mailing list.
+
+```
+* I started a big Amazon machine;
+* I installed Docker and built a custom image containing my software of
+  interest;
+* I ran multiple containers, one connected to port 8000, one on 8001,
+  etc. and gave each student a different port;
+* students could connect in and use the Terminal program in Jupyter to
+  execute commands, and could upload/download files via the Jupyter
+  console interface;
+* in theory I could have used notebooks too, but for this I didn’t have
+  need.
+
+I am aware that JupyterHub can probably do all of this including manage
+the containers, but I’m still a bit shy of diving into that; this was
+fairly straightforward, gave me disposable containers that were isolated
+for each individual student, and worked almost flawlessly.  Should be
+easy to do with RStudio too.
+```
+
+### Cal Poly San Luis Obispo
+
+- [jupyterhub-deploy-teaching](https://github.com/jupyterhub/jupyterhub-deploy-teaching) based on work by Brian Granger for Cal Poly's Data Science 301 Course
+
+### Chameleon
+
+[Chameleon](https://www.chameleoncloud.org) is a NSF-funded configurable experimental environment for large-scale computer science systems research with [bare metal reconfigurability](https://chameleoncloud.readthedocs.io/en/latest/technical/baremetal.html). Chameleon users utilize JupyterHub to document and reproduce their complex CISE and networking experiments.
+
+- [Shared JupyterHub](https://jupyter.chameleoncloud.org): provides a common "workbench" environment for any Chameleon user.
+- [Trovi](https://www.chameleoncloud.org/experiment/share): a sharing portal of experiments, tutorials, and examples, which users can launch as a dedicated isolated environments on Chameleon's JupyterHub.
+
+### Clemson University
+
+- Advanced Computing
+  - [Palmetto cluster and JupyterHub](https://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
+
+### University of Colorado Boulder
+
+- (CU Research Computing) CURC
+
+  - [JupyterHub User Guide](https://curc.readthedocs.io/en/latest/gateways/jupyterhub.html)
+    - Slurm job dispatched on Crestone compute cluster
+    - log troubleshooting
+    - Profiles in IPython Clusters tab
+  - [Parallel Processing with JupyterHub tutorial](https://curc.readthedocs.io/en/latest/gateways/parallel-programming-jupyter.html)
+
+### George Washington University
+
+- [JupyterHub](https://go.gwu.edu/jupyter) with university single-sign-on. Deployed early 2017.
+
+### HTCondor
+
+- [HTCondor Python Bindings Tutorial from HTCondor Week 2017 includes information on their JupyterHub tutorials](https://research.cs.wisc.edu/htcondor/HTCondorWeek2017/presentations/TueBockelman_Python.pdf)
+
+### University of Illinois
+
+- https://datascience.business.illinois.edu (currently down; checked 10/26/22)
+
+### IllustrisTNG Simulation Project
+
+- [JupyterHub/Lab-based analysis platform, part of the TNG public data release](https://www.tng-project.org/data/)
+
+### MIT and Lincoln Labs
+
+- https://supercloud.mit.edu/
+
+### Michigan State University
+
+- [Setting up JupyterHub](https://mediaspace.msu.edu/media/Setting+Up+Your+JupyterHub+Password/1_hgv13aag/11980471)
+
+### University of Minnesota
+
+- [JupyterHub Inside HPC](https://insidehpc.com/tag/jupyterhub/)
+
+### University of Missouri
+
+- https://dsa.missouri.edu/faq/
+
+### Paderborn University
+
+- [Data Science (DICE) group](https://dice-research.org)
+  - [nbgraderutils](https://github.com/dice-group/nbgraderutils): Use JupyterHub + nbgrader + iJava kernel for online Java exercises. Used in lecture Statistical Natural Language Processing.
+
+### Penn State University
+
+- [Press release](https://news.psu.edu/story/523093/2018/05/24/new-open-source-web-apps-available-students-and-faculty): "New open-source web apps available for students and faculty"
+
+### University of California San Diego
+
+- San Diego Supercomputer Center - Andrea Zonca
+
+  - [Deploy JupyterHub on a Supercomputer with SSH](https://zonca.github.io/2017/05/jupyterhub-hpc-batchspawner-ssh.html)
+  - [Run Jupyterhub on a Supercomputer](https://zonca.github.io/2015/04/jupyterhub-hpc.html)
+  - [Deploy JupyterHub on a VM for a Workshop](https://zonca.github.io/2016/04/jupyterhub-sdsc-cloud.html)
+  - [Customize your Python environment in Jupyterhub](https://zonca.github.io/2017/02/customize-python-environment-jupyterhub.html)
+  - [Jupyterhub deployment on multiple nodes with Docker Swarm](https://zonca.github.io/2016/05/jupyterhub-docker-swarm.html)
+  - [Sample deployment of Jupyterhub in HPC on SDSC Comet](https://zonca.github.io/2017/02/sample-deployment-jupyterhub-hpc.html)
+
+- Educational Technology Services - Paul Jamason
+  - [datahub.ucsd.edu](https://datahub.ucsd.edu)
+
+### TACC University of Texas
+
+### Texas A&M
+
+- Kristen Thyng - Oceanography
+  - [Teaching with JupyterHub and nbgrader](http://kristenthyng.com/blog/2016/09/07/jupyterhub+nbgrader/)
+
+### Elucidata
+
+- What's new in Jupyter Notebooks @[Elucidata](https://elucidata.io/):
+  - [Using Jupyter Notebooks with Jupyterhub on GCP, managed by GKE](https://medium.com/elucidata/why-you-should-be-using-a-jupyter-notebook-8385a4ccd93d)
+
+## Service Providers
+
+### AWS
+
+- [Run Jupyter Notebook and JupyterHub on Amazon EMR](https://aws.amazon.com/blogs/big-data/running-jupyter-notebook-and-jupyterhub-on-amazon-emr/)
+
+### Google Cloud Platform
+
+- [Using Tensorflow and JupyterHub in Classrooms](https://cloud.google.com/solutions/using-tensorflow-jupyterhub-classrooms)
+- [using-tensorflow-and-jupyterhub blog post](https://opensource.googleblog.com/2016/10/using-tensorflow-and-jupyterhub.html)
+
+### Everware
+
+[Everware](https://github.com/everware) Reproducible and reusable science powered by jupyterhub and docker. Like nbviewer, but executable. CERN, Geneva [website](http://everware.xyz/)
+
+### Microsoft Azure
+
+- [Azure Data Science Virtual Machine release notes](https://docs.microsoft.com/en-us/azure/machine-learning/machine-learning-data-science-linux-dsvm-intro)
+
+### Rackspace Carina
+
+- https://getcarina.com/blog/learning-how-to-whale/
+- https://carolynvanslyck.com/talk/carina/jupyterhub/#/ (but carolynvanslyck is currently down; checked 10/26/22)
+
+### Hadoop
+
+- [Deploying JupyterHub on Hadoop](https://jupyterhub-on-hadoop.readthedocs.io)
+
+## Miscellaneous
+
+- https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1
+- [Mailing list UT deployment](https://groups.google.com/g/jupyter/c/nkPSEeMr8c0)
+- [JupyterHub setup on Centos](https://gist.github.com/johnrc/604971f7d41ebf12370bf5729bf3e0a4)
+- [Deploy JupyterHub to Docker Swarm](https://jupyterhub.surge.sh)
+- https://www.laketide.com/building-your-lab-part-3/
+- https://estrellita.hatenablog.com/entry/2015/07/31/083202
+- https://www.walkingrandomly.com/?p=5734
+- https://wrdrd.com/docs/consulting/education-technology
+- https://bitbucket.org/jackhale/fenics-jupyter
+- [LinuxCluster blog](https://linuxcluster.wordpress.com/category/application/jupyterhub/)
+- [Spark Cluster on OpenStack with Multi-User Jupyter Notebook](https://arnesund.com/2015/09/21/spark-cluster-on-openstack-with-multi-user-jupyter-notebook/)

docs/source/reference/technical-reference/monitoring/monitoring.md

@@ -16,5 +16,5 @@ tool like [Grafana](https://grafana.com).
 ```{toctree}
 :maxdepth: 2
 
-metrics
+/reference/metrics
 ```

docs/source/reference/technical-reference/subsystems/authenticators.md

@@ -1,3 +1,5 @@
+(authenticators-reference)=
+
 # Authenticators
 
 The {class}`.Authenticator` is the mechanism for authorizing users to use the

docs/source/reference/technical-reference/subsystems/spawners.md

@@ -1,3 +1,5 @@
+(spawners-reference)=
+
 # Spawners
 
 A [Spawner][] starts each single-user notebook server.
@@ -175,7 +177,7 @@ This feature is enabled by setting `Spawner.options_form`, which is an HTML form
 inserted unmodified into the spawn form.
 If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
 
-![spawn-form](../images/spawn-form.png)
+![spawn-form](/images/spawn-form.png)
 
 If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
 

docs/source/reference/technical-reference/technical-overview.md

@@ -18,7 +18,7 @@ Notebook server for each person in a group. Three subsystems are started
 by the `jupyterhub` command line program:
 
 - **Hub** (Python/Tornado): manages user accounts, authentication, and
-  coordinates Single User Notebook Servers using a [Spawner](./spawners.md).
+  coordinates Single User Notebook Servers using a [Spawner](spawners-reference).
 
 - **Proxy**: the public-facing part of JupyterHub that uses a dynamic proxy
   to route HTTP requests to the Hub and Single User Notebook Servers.
@@ -28,9 +28,9 @@ by the `jupyterhub` command line program:
 - **Single-User Notebook Server** (Python/Tornado): a dedicated,
   single-user, Jupyter Notebook server is started for each user on the system
   when the user logs in. The object that starts the single-user notebook
-  servers is called a **[Spawner](./spawners.md)**.
+  servers is called a **[Spawner](spawners-reference)**.
 
-![JupyterHub subsystems](../images/jhub-parts.png)
+![JupyterHub subsystems](/images/jhub-parts.png)
 
 ## How the Subsystems Interact
 
@@ -49,14 +49,14 @@ The proxy is the only process that listens on a public interface. The Hub sits
 behind the proxy at `/hub`. Single-user servers sit behind the proxy at
 `/user/[username]`.
 
-Different **[authenticators](./authenticators.md)** control access
+Different **[authenticators](authenticators-reference)** control access
 to JupyterHub. The default one [(PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module) uses the user accounts on the server where
 JupyterHub is running. If you use this, you will need to create a user account
 on the system for each user on your team. However, using other authenticators you can
 allow users to sign in with e.g. a GitHub account, or with any single-sign-on
 system your organization has.
 
-Next, **[spawners](./spawners.md)** control how JupyterHub starts
+Next, **[spawners](spawners-reference)** control how JupyterHub starts
 the individual notebook server for each user. The default spawner will
 start a notebook server on the same machine running under their system username.
 The other main option is to start each server in a separate container, often using [Docker](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/).
@@ -65,10 +65,10 @@ The other main option is to start each server in a separate container, often usi
 
 When a user accesses JupyterHub, the following events take place:
 
-- Login data is handed to the [Authenticator](./authenticators.md) instance for
+- Login data is handed to the [Authenticator](authenticators-reference) instance for
   validation
 - The Authenticator returns the username if the login information is valid
-- A single-user notebook server instance is [spawned](./spawners.md) for the
+- A single-user notebook server instance is [spawned](spawners-reference) for the
   logged-in user
 - When the single-user notebook server starts, the proxy is notified to forward
   requests made to `/user/[username]/*`, to the single-user notebook server.
@@ -121,9 +121,9 @@ all security and runtime files.
 
 There are two basic extension points for JupyterHub:
 
-- How users are authenticated by [Authenticators](./authenticators.md)
+- How users are authenticated by [Authenticators](authenticators-reference)
 - How user's single-user notebook server processes are started by
-  [Spawners](./spawners.md)
+  [Spawners](spawners-reference)
 
 Each is governed by a customizable class, and JupyterHub ships with basic
 defaults for each.