Restructures the docs site

Gemfile

@@ -8,4 +8,7 @@ group :jekyll_plugins do
   gem "github-pages"
   gem "jekyll-timeago"
   gem "jekyll-gfm-admonitions"
+  gem "jekyll-sitemap"
+  gem "jekyll-commonmark-ghpages"
+  gem "jekyll-toc"
 end

Gemfile.lock

@@ -224,6 +224,9 @@ GEM
       mini_i18n (>= 0.8.0)
     jekyll-titles-from-headings (0.5.3)
       jekyll (>= 3.3, < 5.0)
+    jekyll-toc (0.19.0)
+      jekyll (>= 3.9)
+      nokogiri (~> 1.12)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     jemoji (0.13.0)
@@ -313,8 +316,11 @@ PLATFORMS
 DEPENDENCIES
   github-pages
   jekyll (~> 3.10.0)
+  jekyll-commonmark-ghpages
   jekyll-gfm-admonitions
+  jekyll-sitemap
   jekyll-timeago
+  jekyll-toc
 
 BUNDLED WITH
    2.7.2

README.md

@@ -1,8 +1,76 @@
 # MapSwipe Docs!
+
 This repository contains all the documents related to MapSwipe
 
 - [Overview](/docs/overview.md)
 - [About Data](/docs/about_data.md)
 - [For project managers](/docs/for_project_managers.md)
 
-- [Docs local development](/docs/docs_local_development.md)
+## Getting Started
+
+```bash
+# Get the repository
+git clone https://github.com/mapswipe/mapswipe-docs
+
+# Install jekyll
+gem install jekyll bundler --verbose
+
+# Install dependencies
+bundle install
+```
+
+> [!IMPORTANT]
+> Run this after changing the Gemfile
+
+## Run Docs in Dev Mode
+
+```bash
+bundle exec jekyll serve --livereload
+```
+
+## Refreshing the Sample Export Data
+
+The point of this workflow is to keep the example exports under
+`assets/docs/about_data/files/` consistent. Once exports are updated, the data
+can also be used to keep the description for exports up-to-date.
+
+Two helper scripts under `examples/` fetch the data from the MapSwipe GraphQL backend.
+
+### Fetch Project Exports
+
+```bash
+uv run examples/fetch-project-data/run.py 2962 \
+  --sample 10 \
+  --out assets/docs/about_data/files/project_exports
+```
+
+### Fetch Global Exports
+
+```bash
+uv run examples/fetch-global-data/run.py \
+  --sample 10 \
+  --out assets/docs/about_data/files/global_exports
+```
+
+### Projects Mapping
+
+| Name | id | firebaseId |
+| --- | --- | --- |
+| Find Features - Find Buildings - Mozambique Floods 2026 - Chibuto (1) HOT | 2962 | 01KMMX0C9MG396SCV8W8CZ8RY3 |
+
+
+## Changing the Syntax Highlighting Theme
+
+Fenced code blocks are colored by [Rouge](https://github.com/rouge-ruby/rouge),
+wired into CommonMark via `syntax_highlighter: rouge` in `_config.yml`. The
+active theme is generated to `assets/css/syntax.css`.
+
+To switch themes, run the following commands:
+
+```bash
+# List every theme Rouge ships with
+bundle exec rougify help style
+
+# Regenerate the stylesheet
+bundle exec rougify style gruvbox.dark > assets/css/syntax.css
+```

_config.yml

@@ -1,5 +1,97 @@
-markdown: GFM
+# Site metadata
+title: MapSwipe Docs
+description: Documentation for MapSwipe platform
+url: https://docs.mapswipe.org
 repository: mapswipe/mapswipe-docs
 
+# Plugins
 plugins:
+  - jekyll-remote-theme
+  - jekyll-commonmark-ghpages
   - jekyll-gfm-admonitions
+  - jekyll-seo-tag
+  - jekyll-sitemap
+  - jekyll-toc
+
+# Markdown processor (jekyll-commonmark-ghpages)
+markdown: CommonMarkGhPages
+commonmark:
+  options:
+    - SMART
+    - UNSAFE
+  extensions:
+    - strikethrough
+    - autolink
+    - table
+    - tagfilter
+    - tasklist
+  syntax_highlighter: rouge
+  syntax_highlighter_opts:
+    default_lang: text
+
+# Theme: just-the-docs (loaded via jekyll-remote-theme)
+remote_theme: just-the-docs/just-the-docs
+color_scheme: mapswipe
+
+# UI: Search
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 2
+  preview_words_before: 3
+  preview_words_after: 3
+  tokenizer_separator: /[\s\-/]+/
+  rel_url: true
+  button: false
+
+# UI: Anchor links on headings
+heading_anchors: true
+
+# UI: Top-right auxiliary links
+aux_links:
+  Community: https://community.mapswipe.org
+  Website: https://mapswipe.org
+  Manager Dashboard: https://managers.mapswipe.org
+aux_links_new_tab: true
+
+# UI: "Edit this page" footer link
+gh_edit_link: true
+gh_edit_link_text: "Edit this page"
+gh_edit_repository: "https://github.com/mapswipe/mapswipe-docs"
+gh_edit_branch: "main"
+gh_edit_view_mode: "edit"
+
+# UI: Footer
+footer_content: 'Copyright © MapSwipe. Distributed under the project license.'
+
+# UI: Back-to-top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# UI: Copy-to-clipboard button on fenced code blocks
+enable_copy_code_button: true
+
+# In-page Table of Contents (jekyll-toc)
+toc:
+  min_level: 2
+  max_level: 4
+  ordered_list: false
+  no_toc_section_class: no-toc
+
+# Page defaults (Jekyll core)
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: page
+      toc: true
+
+# Build exclusions (Jekyll core)
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+  - pre-push.sh
+  - .pre-commit-config.yaml
+  - typos.toml
+  - .lycheeignore

_includes/head_custom.html

@@ -0,0 +1,6 @@
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lato:wght@300;400;700&family=DM+Sans:wght@400;500;600;700&display=swap">
+
+<!-- Rouge syntax theme. -->
+<link rel="stylesheet" href="{{ '/assets/css/syntax.css' | relative_url }}">

_layouts/page.html

@@ -0,0 +1,21 @@
+---
+layout: default
+---
+{%- assign anchored = content | inject_anchors -%}
+{%- if page.toc and content contains '<h2' and anchored contains '</h1>' -%}
+  {%- assign parts = anchored | split: '</h1>' -%}
+  {{ parts[0] }}</h1>
+  <nav class="page-toc" aria-label="Table of contents">
+    <p class="page-toc-title">Table of contents</p>
+    {{ content | toc_only }}
+  </nav>
+  {{ parts | slice: 1, 999 | join: '</h1>' }}
+{%- elsif page.toc and content contains '<h2' -%}
+  <nav class="page-toc" aria-label="Table of contents">
+    <p class="page-toc-title">Table of contents</p>
+    {{ content | toc_only }}
+  </nav>
+  {{ anchored }}
+{%- else -%}
+  {{ anchored }}
+{%- endif -%}

_sass/color_schemes/mapswipe.scss

@@ -0,0 +1,133 @@
+// MapSwipe color scheme derived from mapswipe.org
+
+// Brand tokens (mirroring mapswipe.org's CSS custom properties)
+$brand-color: #0f193f;
+$brand-dark-color: #020e3b;
+$accent-color: #aabe5d;
+$accent-dark-color: #8a9b49;
+$white: #ffffff;
+
+// Typography
+$body-font-family: "Lato", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+  Oxygen, Ubuntu, Cantarell, "Helvetica Neue", Arial, sans-serif;
+$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace;
+$body-heading-font-family: "DM Sans", $body-font-family;
+
+$root-font-size: 16px;
+$body-line-height: 1.6;
+$content-line-height: 1.6;
+$body-heading-line-height: 1.25;
+
+// Heading scale used to override just-the-docs's defaults
+$heading-font-weight: 600;
+$h1-font-size: 2rem;
+$h2-font-size: 1.5rem;
+$h3-font-size: 1.25rem;
+$h4-font-size: 1.05rem;
+
+// Just-the-Docs surface colors
+$body-background-color: $white;
+$sidebar-color: #f6f8ff;
+$search-background-color: $white;
+$table-background-color: $white;
+$code-background-color: #f5f5f5;
+$feedback-color: darken($sidebar-color, 3%);
+
+$body-text-color: #5b5b5b;
+$body-heading-color: #000000;
+$nav-child-link-color: $body-text-color;
+$search-result-preview-color: #757575;
+
+$link-color: #0060c9;
+$btn-primary-color: $brand-color;
+$base-button-color: $white;
+
+$border-color: #d0d0d0;
+
+// Just-the-Docs overrides applied at root for things the variables don't expose
+.main-content {
+  h1, .text-alpha {
+    font-weight: $heading-font-weight !important;
+    font-size: $h1-font-size !important;
+  }
+  h2, .text-beta {
+    font-weight: $heading-font-weight !important;
+    font-size: $h2-font-size !important;
+  }
+  h3, .text-gamma {
+    font-weight: $heading-font-weight !important;
+    font-size: $h3-font-size !important;
+  }
+  h4, .text-delta {
+    font-weight: $heading-font-weight !important;
+    font-size: $h4-font-size !important;
+    text-transform: none;
+    letter-spacing: normal;
+  }
+  h5, h6 {
+    font-weight: $heading-font-weight !important;
+  }
+
+  a {
+    color: $link-color;
+  }
+}
+
+.site-title {
+  color: $brand-color !important;
+  font-family: $body-heading-font-family;
+  font-weight: $heading-font-weight;
+}
+
+.site-header {
+  border-bottom: 1px solid $border-color;
+}
+
+.site-nav .nav-list .nav-list-item .nav-list-link.active {
+  color: $brand-color;
+  font-weight: $heading-font-weight;
+}
+
+.btn-primary {
+  background-image: linear-gradient($brand-color, $brand-dark-color);
+  background-color: $brand-color;
+  color: $white;
+}
+
+.btn-primary:hover {
+  background-image: linear-gradient($brand-dark-color, $brand-dark-color);
+}
+
+a.btn:hover {
+  color: $white;
+}
+
+// Just-the-Docs code-block container style reset
+div.highlighter-rouge,
+div.highlighter-rouge pre.highlight,
+figure.highlight,
+figure.highlight pre,
+pre.highlight,
+.highlight pre,
+.highlight .table-wrapper,
+.highlight .table-wrapper td,
+.highlight .table-wrapper pre {
+  background-color: transparent !important;
+  color: inherit !important;
+}
+
+// In-page table of contents - generated by jekyll-toc
+.page-toc {
+  margin: 1.5rem 0 2rem;
+}
+
+.page-toc-title {
+  font-weight: $heading-font-weight !important;
+  font-size: $h4-font-size !important;
+  text-transform: none;
+  letter-spacing: normal;
+
+  margin: 0 0 0.5rem;
+  font-family: $body-heading-font-family;
+  color: $body-heading-color;
+}