Merge pull request #7 from mapswipe/feat/theme

Restructures the docs site

Author: tnagorra

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 .env
 _site
+.jekyll-metadata

.pre-commit-config.yaml

@@ -4,7 +4,13 @@ repos:
     hooks:
       - id: lychee
         files: \.md$
-        args: ["--no-progress", "--root-dir=.", "."]
+        args:
+          - "--no-progress"
+          - "--root-dir=."
+          - "--exclude-path=_includes"
+          - "--exclude-path=_layouts"
+          - "--exclude-path=_site"
+          - "."
         pass_filenames: false
 
   - repo: https://github.com/crate-ci/typos

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,111 @@
-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
+  - jekyll-relative-links
+
+# Rewrite Markdown links to *.md files into their rendered permalinks at build
+# time. Lets us author plain relative .md links (which lychee can verify on
+# disk) instead of hand-maintaining permalink URLs.
+relative_links:
+  enabled: true
+  collections: false
+
+# 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.'
+last_edit_timestamp: true
+
+# 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
+
+# UI: Mermaid diagrams in fenced ```mermaid blocks (just-the-docs theme)
+# Version picked from https://www.jsdelivr.com/package/npm/mermaid
+mermaid:
+  version: "11.4.1"
+
+# 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&family=Patrick+Hand&display=swap">
+
+<!-- Rouge syntax theme. -->
+<link rel="stylesheet" href="{{ '/assets/css/syntax.css' | relative_url }}">

_includes/mermaid_config.js

@@ -0,0 +1,20 @@
+{
+  theme: "neutral",
+  look: "handDrawn",
+  themeVariables: {
+    fontSize: "18px",
+    fontFamily: "'Patrick Hand', 'Caveat', cursive"
+  },
+  flowchart: {
+    nodeSpacing: 160,
+    rankSpacing: 80,
+    padding: 20
+  },
+  state: {
+    padding: 30,
+    titleTopMargin: 30,
+    dividerMargin: 20,
+    nodeSpacing: 160,
+    rankSpacing: 80
+  }
+}

_includes/toc_heading_custom.html

@@ -0,0 +1 @@
+<h2 class="text-delta">Continue reading</h2>

_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 -%}