docs: add mkdocs (#9)

Adds:

- CI with simple linting
- Pages workflow for deploying on tag push. Note that this won't deploy
anything for now, we'll have to manually backfill the old versions

cc @hrodmn

Closes #8

Author: gadomski

.github/workflows/ci.yaml

@@ -0,0 +1,15 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: DavidAnson/markdownlint-cli2-action@v20

.github/workflows/pages.yaml

@@ -0,0 +1,24 @@
+name: Pages
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pages:
+    name: Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Deploy docs
+        env:
+          GIT_COMMITTER_NAME: CI
+          GIT_COMMITTER_EMAIL: [email protected]
+        run: |
+          # Get most recent git tag
+          # https://stackoverflow.com/a/7261049
+          VERSION=$(git describe --tags --abbrev=0)
+          mike deploy $VERSION latest --update-aliases --push

.gitignore

@@ -0,0 +1,2 @@
+.cache
+node_modules

.markdownlint-cli2.jsonc

@@ -0,0 +1,7 @@
+{
+  "config": {
+    "line-length": false,
+  },
+  "gitignore": true,
+  "globs": ["**/*.md"],
+}

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -21,10 +21,31 @@ For analytic questions like "find the items in the Sentinel-2 collection in June
 
 ## Development
 
-Validate the example collection metadata against the jsonschema:
+Get [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```sh
+uv sync
+npm install
+```
+
+To lint the markdown files:
+
+```sh
+npm run lint
+# or, to fix errors
+npm run format
+```
+
+To serve the documentation site:
+
+```sh
+uv run mkdocs serve
+```
+
+To validate the example collection metadata against the jsonschema:
 
 ```shell
-check-jsonschema --schemafile spec/json-schema/metadata.json spec/example-metadata.json
+uv run check-jsonschema --schemafile json-schema/metadata.json example-metadata.json
 ```
 
 ## History

docs/drawbacks.md

@@ -52,7 +52,3 @@ Then when the second item is converted back to JSON, it will be returned as
 ```
 
 which is not strictly equal to the input.
-
-## Schema difficulties
-
-JSON is schemaless while Parquet requires a strict schema, and it can be very difficult to unite these two systems. This is such an important consideration that we have a [documentation page](./schema.md) just to discuss this point.

docs/index.md

@@ -0,0 +1 @@
+../stac-geoparquet-spec.md

mkdocs.yml

@@ -0,0 +1,39 @@
+site_name: stac-geoparquet-spec
+site_url: https://radiantearth.github.io/stac-geoparquet-spec/
+repo_url: https://github.com/radiantearth/stac-geoparquet-spec
+repo_name: stac-geoparquet-spec
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: deep purple
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep purple
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+nav:
+  - index.md
+  - drawbacks.md
+
+plugins:
+  - search
+  - social
+  - mike:
+      alias_type: "copy"
+      canonical_version: "latest"
+
+extra:
+  version:
+    provider: mike