wip mkdocs

.gitignore

@@ -8,6 +8,7 @@ dist
 .DS_Store
 # So that notebooks are only included _intentionally_
 *.ipynb
+.cache
 
 # pixi environments
 .pixi

docs/how-it-works.md

@@ -0,0 +1,24 @@
+# How it works?
+
+
+Lonboard is built on four foundational technologies: deck.gl, GeoArrow, GeoParquet, and anywidget.
+
+[deck.gl](https://deck.gl/) is a JavaScript geospatial data visualization library. Because deck.gl uses the GPU in your computer to render data, it's capable of performantly rendering very large quantities of data.
+
+[GeoArrow](https://geoarrow.org/) is a memory format for efficiently representing geospatial vector data. As a memory format, GeoArrow is not compressed and can be used directly.
+
+[GeoParquet](https://geoparquet.org/) is a file format for efficiently encoding and decoding geospatial vector data. As a file format, GeoParquet contains very efficient compression, and needs to be parsed before it can be used. [^1]
+
+[^1]: lonboard currently doesn't use "official" GeoParquet 1.0, because the 1.0 spec requires encoding geometries as Well-Known Binary (WKB) inside of the Parquet file. lonboard uses the highly-efficient GeoArrow encoding inside of GeoParquet (which may [become part of the GeoParquet spec in 1.1](https://github.com/opengeospatial/geoparquet/issues/185)). This is faster and easier to write when the writer and reader are both using GeoArrow anyways.
+
+[anywidget](https://anywidget.dev/) is a framework for building custom Jupyter widgets that makes the process much easier than before.
+
+## How is it so fast?
+
+Lonboard is so fast because it moves data from Python to JavaScript (in your browser) and then from JavaScript to your Graphics Processing Unit (GPU) more efficiently than ever before.
+
+Other Python libraries for interactive maps exist (such as [`ipyleaflet`](https://github.com/jupyter-widgets/ipyleaflet)), and even existing bindings to deck.gl exist (such as [`pydeck`](https://pypi.org/project/pydeck/)). But those libraries encode data as GeoJSON to copy from Python to the browser. GeoJSON is **extremely slow** to read and write and results in a very large data file that has to be copied to the browser.
+
+With lonboard, the _entire pipeline_ is binary. In Python, GeoPandas to GeoArrow to GeoParquet avoids a text encoding like GeoJSON and results in a compressed binary buffer that can be efficiently copied to the browser. In JavaScript, GeoParquet to GeoArrow offers efficient decoding (in WebAssembly). Then deck.gl is able to interpret the GeoArrow table _directly_ without any parsing (thanks to [`@geoarrow/deck.gl-layers`](https://github.com/geoarrow/deck.gl-layers)).
+
+The end user doesn't care about rendering _GeoJSON_, they want to render _their data_. Lonboard focuses on abstracting how to most efficiently move data so that the end user doesn't have to think about it.

mkdocs.yml

@@ -0,0 +1,82 @@
+site_name: lonboard
+repo_url: https://github.com/developmentseed/lonboard
+site_description: Extremely fast geospatial data visualization in Jupyter Notebooks
+site_author: Development Seed
+site_url: https://developmentseed.org/lonboard
+docs_dir: docs
+
+extra:
+  social:
+    - icon: "fontawesome/brands/github"
+      link: "https://github.com/developmentseed"
+    - icon: "fontawesome/brands/twitter"
+      link: "https://twitter.com/developmentseed"
+    - icon: "fontawesome/brands/medium"
+      link: "https://medium.com/devseed"
+
+nav:
+  - "index.md"
+  - "How it works?": how-it-works.md
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: teal
+      accent: indigo
+      toggle:
+        icon: material/lightbulb
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: teal
+      accent: indigo
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # logo: img/geopolars_logo.svg
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - search.suggest
+    - search.share
+
+plugins:
+  - search
+  - social
+
+# https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
+markdown_extensions:
+  - admonition
+  - attr_list
+  - codehilite:
+      guess_lang: false
+  - def_list
+  - footnotes
+  - pymdownx.arithmatex
+  - pymdownx.betterem
+  - pymdownx.caret:
+      insert: false
+  - pymdownx.details
+  - pymdownx.emoji
+  - pymdownx.escapeall:
+      hardbreak: true
+      nbsp: true
+  - pymdownx.magiclink:
+      hide_protocol: true
+      repo_url_shortener: true
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - toc:
+      permalink: true