diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 2a7327c..ce401bf 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -1,6 +1,6 @@ name: Pages -# Publishes the project site to GitHub Pages: the landing page (site/index.html) at the root +# Publishes the project site to GitHub Pages: the landing page (site/public/) at the root # and the guides (docs/*.md, CHANGELOG.md) under /docs/, built by site/build.sh with MkDocs. # Needs Settings → Pages → Source: GitHub Actions. diff --git a/AGENTS.md b/AGENTS.md index e5b289c..f25bc33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,7 +84,8 @@ adb logcat -s MeshAnd MeshAnd/SDK - **Releases:** `.github/workflows/release.yml` runs on a `v*` tag. It requires the tag to equal `versionName`, signs using the secrets `MESHAND_KEYSTORE_BASE64` and `MESHAND_KEYSTORE_PASSWORD`, and publishes `MeshAnd-.apk` to GitHub Releases. - **Website:** the project site at https://meshand.app/, published by `.github/workflows/pages.yml` on pushes to `main` that touch `site/`, `docs/` or `CHANGELOG.md`, or by hand (Run workflow). The repo's Settings → Pages → Source must be **GitHub Actions**. - Domain: `meshand.app`, registered and DNS-hosted on Cloudflare (account "P13 Private", 2026-10-22). Apex `A`/`AAAA` records point to GitHub Pages (`185.199.108–111.153`, `2606:50c0:8000–8003::153`) and `www` is a `CNAME` to `mategogiberidze.github.io`, all **DNS only** (not proxied), so GitHub issues the HTTPS certificate. The custom domain is set in Settings → Pages; with Actions deploys there is no `CNAME` file. - - `/` is `site/index.html`, one hand-written static page. `/docs/` holds the guides: `site/build.sh` copies `docs/*.md`, `CHANGELOG.md` (as `changelog.md`) and `site/guides/` (overview page, logo, CSS) into `build/site-docs/` and renders them with MkDocs Material (`site/mkdocs.yml`, versions pinned in `site/requirements.txt`, `--strict`). The `.md` files stay the only source; don't copy guide text into `site/`. + - `/` is `site/public/`: `index.html` (one hand-written static page), `404.html`, `robots.txt`, `sitemap.xml` (the landing page only; the guides have MkDocs' `/docs/sitemap.xml`, and `robots.txt` lists both) and `apple-touch-icon.png`. `build.sh` adds `favicon.svg` (the logo) and `images/social-preview.png` from `docs/images/`. `/docs/` holds the guides: `site/build.sh` copies `docs/*.md`, `CHANGELOG.md` (as `changelog.md`) and `site/guides/` (overview page, logo, CSS) into `build/site-docs/` and renders them with MkDocs Material (`site/mkdocs.yml`, versions pinned in `site/requirements.txt`, `--strict`). The `.md` files stay the only source; don't copy guide text into `site/`. + - SEO: the landing page has a meta description, Open Graph tags, JSON-LD (`WebSite` + `SoftwareApplication`) and a visible FAQ. Each guide gets its own `` and description from `site/hooks.py` (so `docs/*.md` need no front matter) and Open Graph tags from `site/theme/main.html`. Keep JSON-LD and FAQ answers true to the app; don't add ratings or reviews. - Material for MkDocs is in maintenance mode and incompatible with MkDocs 2.0, so keep `mkdocs` pinned below 2.0. - Preview: `pip install -r site/requirements.txt && ./site/build.sh`, then `python3 -m http.server -d build/site`. - A link between guides on GitHub (`../CHANGELOG.md`) is rewritten by `build.sh`; a new kind of cross-folder link needs the same, or `--strict` fails. diff --git a/site/build.sh b/site/build.sh index 40a7898..9faec57 100755 --- a/site/build.sh +++ b/site/build.sh @@ -1,13 +1,14 @@ #!/usr/bin/env bash # Builds the GitHub Pages site into build/site: -# / the landing page (site/index.html) +# / the landing page and other root files (site/public/), plus the favicon and the +# social preview image from docs/images and the logo # /docs/ the guides: docs/*.md and CHANGELOG.md rendered by MkDocs Material (site/mkdocs.yml) # Needs the packages in site/requirements.txt. Used by .github/workflows/pages.yml. set -euo pipefail cd "$(dirname "$0")/.." rm -rf build/site build/site-docs -mkdir -p build/site build/site-docs +mkdir -p build/site/images build/site-docs # The guides' sources: our overview page and assets, the docs, and the changelog. cp -R site/guides/. build/site-docs/ @@ -19,4 +20,7 @@ rm build/site-docs/*.bak # mkdocs is pinned below 2.0 in requirements.txt, so Material's MkDocs 2.0 warning doesn't apply. NO_MKDOCS_2_WARNING=true mkdocs build --strict --config-file site/mkdocs.yml --site-dir "$PWD/build/site/docs" -cp site/index.html build/site/ + +cp -R site/public/. build/site/ +cp site/guides/assets/logo.svg build/site/favicon.svg +cp docs/images/social-preview.png build/site/images/ diff --git a/site/hooks.py b/site/hooks.py new file mode 100644 index 0000000..e374e1a --- /dev/null +++ b/site/hooks.py @@ -0,0 +1,37 @@ +"""MkDocs hook: search-friendly titles and descriptions for the guides. + +They live here rather than as front matter, so the Markdown files in docs/ stay plain on GitHub. +Keys are the file names in build/site-docs (see build.sh). +""" + +PAGES = { + "index.md": ( + "Guides for Meshtastic teams on OsmAnd", + "Guides for MeshAnd, the Android app that shows your Meshtastic team live on the OsmAnd " + "map: radio setup, release notes and building the app.", + ), + "radio-setup.md": ( + "Meshtastic radio setup for live team tracking", + "Channel, role and position settings that make Meshtastic teammates move smoothly on the " + "map: a private channel, faster position updates and the Client role.", + ), + "changelog.md": ( + "Release notes", + "What changed in each version of MeshAnd, the Android app that shows your Meshtastic team " + "on the OsmAnd map.", + ), + "development.md": ( + "Building MeshAnd from source", + "Build MeshAnd with Android Studio, see how the code is organised, read the logs, publish " + "a release and debug Bluetooth.", + ), +} + + +def on_page_markdown(markdown, page, **kwargs): + title, description = PAGES.get(page.file.src_uri, (None, None)) + if title: + page.meta.setdefault("title", title) + if description: + page.meta.setdefault("description", description) + return markdown diff --git a/site/mkdocs.yml b/site/mkdocs.yml index 334c1f5..314e92c 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -1,9 +1,10 @@ # MkDocs Material config for the guides under /docs/ on the project site. # Don't run mkdocs directly: site/build.sh gathers docs/*.md and CHANGELOG.md into # build/site-docs first and puts the result next to the landing page. +# hooks.py sets each page's <title> and description; theme/main.html adds social-preview tags. -site_name: MeshAnd guides -site_description: Guides for MeshAnd, the Android app that shows your Meshtastic team on the OsmAnd map. +site_name: MeshAnd +site_description: Guides for MeshAnd, the Android app that shows your Meshtastic team live on the OsmAnd map. site_url: https://meshand.app/docs/ repo_url: https://github.com/mategogiberidze/MeshAnd repo_name: mategogiberidze/MeshAnd @@ -20,6 +21,7 @@ nav: theme: name: material + custom_dir: theme logo: assets/logo.svg favicon: assets/logo.svg # System fonts, as on the landing page: no requests to Google Fonts. @@ -57,6 +59,9 @@ extra: link: https://github.com/mategogiberidze/MeshAnd name: MeshAnd on GitHub +hooks: + - hooks.py + extra_css: - assets/extra.css diff --git a/site/public/404.html b/site/public/404.html new file mode 100644 index 0000000..1574de7 --- /dev/null +++ b/site/public/404.html @@ -0,0 +1,41 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>Page not found · MeshAnd + + + + + + + +
+ +

This page is off the map

+

The page you were looking for doesn't exist or has moved.

+ +
+ + diff --git a/site/public/apple-touch-icon.png b/site/public/apple-touch-icon.png new file mode 100644 index 0000000..918b9cb Binary files /dev/null and b/site/public/apple-touch-icon.png differ diff --git a/site/index.html b/site/public/index.html similarity index 86% rename from site/index.html rename to site/public/index.html index 2effb6a..3622cae 100644 --- a/site/index.html +++ b/site/public/index.html @@ -3,20 +3,63 @@ -MeshAnd: your Meshtastic team on the OsmAnd map - +MeshAnd: your Meshtastic team live on the OsmAnd map + - + + - + + + - + + +