Hosting options for the Research repo

Research Question

What is the best free or very-low-cost hosting option for this research repository that supports full-text search, and optionally vector/graph database capabilities, without requiring SEO, custom DNS, or authentication?

Findings

Executive Summary

MkDocs Material deployed to GitHub Pages via GitHub Actions — using only the already-approved GITHUB_TOKEN — is the recommended hosting stack for this research repository. A five-line workflow (pip install mkdocs-material && mkdocs gh-deploy --force) converts Research/completed/ Markdown to a navigable HTML site with tag indexes and built-in full-text search; Pagefind can be layered on as a post-processor to add tag-filtered, section-level search with under 50 kB payload at current corpus scale. No cloud-hosted vector database is free forever without a new credential; the only zero-credential path for semantic search is pre-computed embeddings stored as a static JSON file served by Orama in the browser. The recommended baseline stack requires no new infrastructure, no new credentials, and an estimated 30–60 second CI (continuous integration) build time.

Key Findings

1. GitHub Pages deployed via a custom GitHub Actions workflow requires only GITHUB_TOKEN with pages: write; id-token: write permissions — the only evaluated hosting option requiring no new credential while keeping all build steps inside GitHub Actions. [High confidence]

2. Cloudflare Pages free tier provides unlimited bandwidth versus GitHub Pages' 100 GB/month soft limit, but at the expected traffic scale for a personal research site this difference is not material; both platforms are technically viable. [High confidence]

3. MkDocs Material is the best-fit static-site generator for this repository: it is Python-native (consistent with src/), reads YAML frontmatter tags via its built-in tags plugin, and provides an official GitHub Actions deployment recipe that uses only GITHUB_TOKEN. [High confidence]

4. Pagefind v1.0 is a stable post-processor that indexes built HTML from any SSG and produces a chunked client-side search index; for 50–200 research items the total search payload is under 50 kB, and it supports tag-based filtering via data-pagefind-filter HTML attributes on tag links. [High confidence]

5. Enabling Pagefind tag filtering in a MkDocs Material site requires a small template override to emit data-pagefind-filter="tag" on tag links in the built HTML; without this customisation, tag navigation and keyword search remain separate UI surfaces. [Medium confidence]

6. No free-forever cloud-hosted vector database (Qdrant Cloud, LanceDB Cloud, or Weaviate Cloud) can be integrated without a new API credential not currently in the approved credentials table, making all of them a hard stop under the existing workflow constraints. [High confidence]

7. Orama (open-source JavaScript library) supports browser-side full-text, vector, and hybrid search with no server requirement, using pre-computed embeddings stored as a static JSON file; at 200 research items using 384-dimension embeddings the JSON file is approximately 300 kB, and the CI embedding generation step adds roughly 60–90 seconds to each build. [Medium confidence]

8. LanceDB Cloud is in public beta with a 30-day free trial — it is not a free-forever option — and LanceDB OSS is an in-process embedded database that cannot serve queries from a static site without a serverless function wrapper. [High confidence]

9. Neo4j AuraDB Free (50,000 nodes, 175,000 relationships) could support graph-based tag and cross-reference navigation, but at current corpus scale (30–50 items) MkDocs Material's tags index is sufficient and any automated AuraDB integration requires a new credential not in the approved table. [High confidence]

10. The simplest end-to-end stack meeting all stated requirements — free, full-text search with tag filtering, push-to-main GitHub Actions workflow, zero new credentials — is MkDocs Material (SSG) + Pagefind (search post-processor) + GitHub Pages (hosting). [High confidence]

Assumptions

• Assumption: Site traffic will remain low (personal/small-team use). Justification: The research corpus is a personal workflow tool; no public distribution is planned. GitHub Pages' 100 GB/month soft bandwidth limit is not at risk.
• Assumption: The owner can perform one-time dashboard setup (enabling GitHub Pages in repository Settings, choosing "GitHub Actions" as the source). Justification: The owner previously enabled the GitHub wiki via repository Settings for the publish-wiki.yml workflow — this is the same pattern.
• Assumption: The YAML frontmatter tags key in Research/completed/ files is compatible with MkDocs Material's tags plugin format (tags: [tag1, tag2, ...]). Justification: Both use standard YAML list syntax; MkDocs Material supports both YAML list and inline YAML formats.

Analysis

Two binary decisions drive the implementation choice:

Decision 1 — Hosting platform: GitHub Pages is preferred over Cloudflare Pages because it uses only the already-approved GITHUB_TOKEN with no new secrets. Cloudflare Pages native Git integration avoids a CLOUDFLARE_API_TOKEN in GitHub Secrets but moves the build trigger outside GitHub Actions, losing the ability to run Python pre-processing steps (frontmatter reading, nav generation, Pagefind indexing) within the same workflow. The bandwidth ceiling gap (100 GB/month vs. unlimited) is not material at this corpus scale.

Decision 2 — Search capability: Pagefind is preferred over MkDocs Material's built-in lunr search because it supports tag-based filtering within search results (via the data-pagefind-filter mechanism) whereas lunr search and tag navigation are separate surfaces in MkDocs Material. For semantic search, Orama with pre-computed embeddings is the only zero-credential path; the 60–90 s CI overhead is acceptable given the research loop runs on a schedule. If Qdrant Cloud is approved, the pre-computation step in CI pushes embeddings to Qdrant and a Cloudflare Worker (or GitHub Pages + fetch-from-qdrant approach) serves queries — this avoids bundling the embeddings JSON into the site but requires two new credentials (QDRANT_API_KEY and potentially a Cloudflare token).

The MkDocs Material + Pagefind + GitHub Pages stack is therefore the correct baseline. Orama-based semantic search is the correct zero-credential enhancement path. Qdrant Cloud server-side semantic search is the preferred long-term path once credential approval is obtained.

Risks, Gaps, and Uncertainties

• Pagefind template override: Pagefind tag filtering in MkDocs Material requires a community-pattern template override that emits data-pagefind-filter attributes. This is not officially supported by MkDocs Material and may break on theme updates. Mitigation: use MkDocs Material's native tags index as the primary tag navigation; Pagefind tag filter is an enhancement.
• LanceDB Cloud free tier: Currently in public beta with 30-day trial. A permanent free tier has not been announced. If one is launched, LanceDB becomes viable for server-side semantic search without pre-computing embeddings in CI.
• MkDocs Material nav auto-generation: Requires a pre-build Python script to read YAML frontmatter dates and generate mkdocs.yml nav configuration. This script does not yet exist. Estimated implementation: 1–2 hours, using the existing src/research/item.py frontmatter reader.
• GitHub Pages 1 GB site size limit: Not a near-term risk given current corpus growth rate. If the corpus grows to thousands of items, migration to Cloudflare Pages should be revisited.

Open Questions

1. Build trigger path filter: Should the hosted site rebuild on every push to main or only on changes to Research/completed/**? Scoping to Research/completed/** would prevent redundant builds when only code or configuration changes are pushed.
2. Quartz v4 graph view: If the owner values visual graph navigation between research items, Quartz v4 is worth reconsidering despite the Node.js runtime cost. A follow-up item could prototype Quartz on a branch.
3. Qdrant Cloud credential approval: If the owner approves adding QDRANT_API_KEY to GitHub Secrets, what is the correct architecture for the semantic search endpoint — Cloudflare Worker (requires Cloudflare account + CLOUDFLARE_API_TOKEN), GitHub Actions nightly index push (avoids real-time query serving), or GitHub Pages + client-side Qdrant query via Cross-Origin Resource Sharing (CORS) (exposes the key in the browser)?
4. Implementation backlog item: A follow-up BACKLOG.md item should specify the implementation steps for the MkDocs Material + Pagefind + GitHub Pages stack. This research item produces the decision; the backlog item drives the execution.

sources

• [x] GitHub Pages docs — (consulted: limits page)
• [x] Cloudflare Pages comparison — (consulted)
• [x] Vercel vs Netlify vs Cloudflare Pages 2025 — (consulted)
• [x] Pagefind official site — (consulted)
• [x] Pagefind tutorial — (consulted)
• [x] MkDocs Material — (consulted: publishing + tags docs)
• [x] Quartz hosting docs — (consulted)
• [x] Orama search — (consulted)
• [x] Qdrant Cloud pricing — (consulted)
• [x] LanceDB Cloud docs — (consulted)
• [x] Neo4j AuraDB — (consulted)