From 5a8bc501ca90651008522a7f691002e9894052af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Trevor=20Mu=C3=B1oz?= <trevor.munoz@gmail.com>
Date: Tue, 7 Jul 2026 15:28:36 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20restructure=20README=20around=20Di?=
 =?UTF-8?q?=C3=A1taxis=20modes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reorganize the README so its modes stay unmixed and the getting-started
path actually works end to end:

* Add an About section (what the repo is, who it's for, the live site).
* Add a Prerequisites section that lists Hugo (extended) and go-task —
  the previous README omitted Hugo, so a fresh clone running 'task serve'
  hit 'hugo: command not found'.
* Correct the Homebrew formula (task -> go-task) and combine installs.
* Frame the Python setup as the data/API-user path and link the code
  examples and TEST_PYTHON_EXAMPLES.md.
* Add a thin project-structure table.
* Add Contributing (markdownlint conventions) and License (Apache-2.0)
  sections.
---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 89 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 9049a0a..98a4d9b 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,113 @@
 # umd-lib-opendata
 
-University of Maryland Libraries Open Data Website, built using the
-[Hugo](https://gohugo.io/) static site generator.
+Source for the University of Maryland Libraries Open Data website,
+<https://opendata.lib.umd.edu/>. The site is a [Hugo](https://gohugo.io/)
+static site built with the [Hextra](https://github.com/imfing/hextra) theme.
+It documents the APIs, services, and datasets that UMD Libraries makes openly
+available, and ships runnable [Python code examples](static/code) that
+demonstrate how to use them.
 
-## Building
+This README covers two audiences:
 
-Install go-task.
+* **Site contributors** — building and serving the website locally
+  (start with [Prerequisites](#prerequisites)).
+* **Data and API users** — running the example scripts against UMD Libraries
+  services (skip to [Python code examples](#python-code-examples)).
 
-```bash
-# Intall using Homebrew
-brew install task
+## Prerequisites
+
+Building the site requires two command-line tools:
+
+* [Hugo](https://gohugo.io/) — the **extended** edition (the Hextra theme
+  requires it)
+* [go-task](https://taskfile.dev/) — the task runner used for all build
+  commands
+
+On macOS with [Homebrew](https://brew.sh/):
 
-# Install using golang
-go install github.com/go-task/task/v3/cmd/task@latest
+```bash
+brew install hugo go-task
 ```
 
-Build and serve the website using hugo:
+Running the Python code examples additionally requires Python 3.12+ (see
+[Python code examples](#python-code-examples)).
+
+## Getting started
 
-``` bash
+Clone the repository, then start the local development server:
+
+```bash
 task serve
+```
+
+This serves the site with drafts enabled at <http://localhost:1314/> and
+rebuilds automatically as you edit. Open the URL in a browser:
+
+```bash
 open http://localhost:1314/
 ```
 
-For more information see [Hugo CLI docs](https://gohugo.io/commands/).
+Other common tasks:
+
+```bash
+# Build the static site into public/
+task build
+
+# Remove build artifacts
+task clean
+```
+
+For more options, see the [Hugo CLI docs](https://gohugo.io/commands/).
 
-## Python Environment
+## Python code examples
 
-Set up a Python environment to run the [code examples](static/code), using pyenv
-and venv.
+The [`static/code/`](static/code) directory contains standalone Python
+scripts that demonstrate how to query UMD Libraries services (OAI-PMH,
+OpenSearch, the DSpace REST API, JSON-LD, and more). They require Python
+3.12+; the pinned version lives in [`.python-version`](.python-version).
+
+Set up an environment with [pyenv](https://github.com/pyenv/pyenv) and venv:
 
 ```bash
-# Setup the Python version
+# Install the pinned Python version
 pyenv install --skip-existing $(cat .python-version)
 
-# Setup the virtual environment
+# Create and activate a virtual environment
 python -m venv .venv
 source .venv/bin/activate
 
-# Install the requirements
+# Install dependencies
 pip install -r requirements.txt
 ```
+
+Run the examples' test suite to confirm they work:
+
+```bash
+task test-python
+```
+
+See [TEST_PYTHON_EXAMPLES.md](TEST_PYTHON_EXAMPLES.md) for details on testing
+the code examples.
+
+## Project structure
+
+| Path | Contents |
+| --- | --- |
+| `content/` | Site content: `services/`, `apis/`, `datasets/`, `posts/` |
+| `static/code/` | Downloadable Python API examples |
+| `layouts/` | Custom templates and shortcodes overriding Hextra defaults |
+| `hugo.yaml` | Hugo site configuration |
+| `Taskfile.yaml` | Build, serve, and deploy tasks |
+
+Content pages live under `content/` and use the `code` shortcode
+(`layouts/_shortcodes/code.html`) to embed the example scripts.
+
+## Contributing
+
+Markdown content follows [markdownlint](https://github.com/DavidAnson/markdownlint)
+conventions — notably asterisk-style lists (MD004), blank lines around lists
+(MD032), and angle-bracketed bare URLs (MD034).
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).