ADR: Public Documentation Hosting Platform#2740
Open
Copilot wants to merge 10 commits into
Open
Conversation
Co-authored-by: pylipp <10617122+pylipp@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
pylipp
May 28, 2026 08:57
View session
Co-authored-by: pylipp <10617122+pylipp@users.noreply.github.com>
Copilot
AI
changed the title
ADR: Public documentation hosting platform
ADR: Public Documentation Hosting Platform
May 28, 2026
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2740 +/- ##
=======================================
Coverage 76.72% 76.72%
=======================================
Files 302 302
Lines 22289 22289
Branches 2249 2249
=======================================
Hits 17101 17101
Misses 5140 5140
Partials 48 48
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
Contributor
Co-authored-by: pylipp <10617122+pylipp@users.noreply.github.com>
Copilot
AI
changed the title
ADR: Public Documentation Hosting Platform
docs(adr): add Analytics column and explain PWA in summary table
Jun 1, 2026
…for-documentation-options' into copilot/create-adr-for-documentation-options
Contributor
@aerinsol content updated |
pylipp
changed the title
aerinsol
requested changes
Jun 8, 2026
aerinsol
left a comment
aerinsol
left a comment
Member
There was a problem hiding this comment.
Updated consideration rubric. Please update analysis with the new dimensions and problem statement, as well as the learning authorship
Particularly interested in the time to set up and publish vs expandability question as well.
Content maintainability over time and interactivity is more important than PWA / offline support.
| **Description:** Activate the built-in GitHub Wiki on the Boxtribute repository. | ||
|
|
||
| - ✅ Basic non-tech editing via GitHub web UI | ||
| - ❌ Poor discoverability outside GitHub |
| - ✅ Real-time collaboration | ||
| - ✅ Slack integrations | ||
| - ⚠️ Cloud version available (paid) or self-hosted (free but requires maintenance) | ||
| - ❌ No public-facing docs site out of the box (primarily for internal wikis) |
Contributor
|
Cf. #2760 |
Contributor
|
@aerinsol while the research for the ADR was conducted with Claude, I also ran it against Gemini which votes to go for Docusaurus: Summary Table of Evaluated Options
Decision OutcomeChosen Option: Option 2 (Docusaurus / Starlight + Git-Backed Visual CMS like TinaCMS)JustificationOption 2 strikes the ideal balance between Boxtribute's strict core philosophy (Reliability > Sexiness, Minimal maintenance, and Keep it simple) and the complex requirements of field deployment.
ConsequencesPositive Impacts
Negative Impacts / Risks
|
Member
|
Philipp, can you explicitly ask Claude and Gemini to evaluate vs the
learning authorship tools I shared, and tell it to heavily weight my
initial feedback, especially my revised problem statement? It's currently
over weighting your original formulation (I think bc you ask it not to
change code) but you should tell it to consider the original formulation as
exploratory, and my feedback as primary since I'm product owner / HoP.
This revision is not very good and is just regurgitating previous work such
as Mauro's PR. I'd also like you to add some human thinking Philipp since
this revision is not as good as what I've previously seen from you.
…On Tue, Jun 9, 2026, 11:54 PM Philipp Metzner ***@***.***> wrote:
*pylipp* left a comment (boxwise/boxtribute#2740)
<#2740 (comment)>
@aerinsol <https://github.com/aerinsol> while the research for the ADR
was conducted with Claude, I also ran it against Gemini which votes to go
for Docusaurus:
Summary Table of Evaluated Options
Requirement / Criterion Option 1: GitBook (SaaS Non-Profit) Option 2:
Docusaurus / Starlight + Git CMS (Tina/Decap) Option 3: Wiki.js
(Self-Hosted OSS) Option 4: Headless CMS (Directus) + Next.js Frontend
*Financial Cost* Free (via OSS/Non-profit tier) Free (Open source, free
static hosting) Free (Open source software) Free (Open source software)
*Non-Tech Editing* *Excellent* (Intuitive WYSIWYG visual editor) *Good*
(Visual/form web-UI commits to Git in backend) *High* (Built-in rich text
& Markdown editor editors) *Excellent* (Highly tailorable content block
layouts)
*Offline / PWA* *Poor* (No native service worker/offline browsing support)
*Excellent* (Native PWA plugins leveraging Workbox caching) *Poor* (Lacks
built-in deep offline application layer) *Excellent* (Can configure
custom next-pwa service workers)
*Search* *Excellent* (Built-in AI-powered instant search) *Excellent*
(Algolia DocSearch or local search plugins) *Good* (Built-in DB search or
Elasticsearch) *Custom* (Requires manual integration with a search engine)
*Theming* *Medium* (Basic layout customization, colors, logo) *Excellent*
(Full CSS/React framework design control) *Medium* (Theme variables and
injected custom CSS) *Excellent* (Unrestricted frontend layout control)
*Custom Domain* *Yes* (Included in baseline community tiers) *Yes* (Free
configuration via static hosts) *Yes* (Configured via web reverse proxy)
*Yes* (Handled directly at the frontend deployment layer)
*Interactivity* *Medium* (Standard tabs, hints, embeds) *Excellent* (MDX
allows embedding custom React logic) *Medium* (Standard HTML widgets)
*Excellent* (Full freedom to build custom learning applications)
*Analytics* *Good* (Supports third-party script integrations) *Excellent*
(Easy plugin script injection for Plausible) *Good* (Global script
insertion in configuration panel) *Excellent* (Custom telemetry
implementation)
*Self-Hosted Burden* *None* (Fully managed SaaS platform) *Very Low*
(Serverless execution, zero ongoing ops maintenance) *Medium* (Requires
hosting Node.js and PostgreSQL containers) *High* (Requires maintaining
CMS engine, DB, and frontend)
*Time to Set Up* *Very Low* (Immediate onboarding and setup) *Medium*
(Initial repository layout and CMS schema configuration) *Low-Medium*
(Server deployment and container provisioning) *High* (Full architecture
definitions, data mapping, and coding)
------------------------------
Decision Outcome Chosen Option: Option 2 (Docusaurus / Starlight +
Git-Backed Visual CMS like TinaCMS) Justification
Option 2 strikes the ideal balance between Boxtribute's strict core
philosophy (*Reliability > Sexiness*, *Minimal maintenance*, and *Keep it
simple*) and the complex requirements of field deployment.
- *Zero Server Overhead:* Because it compiles directly down to static
assets, it can be hosted for free on serverless infrastructure (e.g.,
GitHub Pages, Cloudflare Pages, Netlify), requiring no server maintenance,
zero database updates, and removing security patching vectors from the
engineering team.
- *Critical Offline Caching:* Unlike GitBook or Wiki.js, Option 2
natively supports robust PWA capabilities via Workbox plugins. This allows
aid workers and operators inside low-connectivity refugee camps to reliably
view documentation and training guides on-demand after their initial visit.
- *Empowered Non-Tech Contribution:* Integrating a Git-backed CMS
(such as TinaCMS or Decap CMS) gives the operations and partnerships teams
a clean, visual web interface to draft and publish changes without needing
to understand Git, terminal commands, or Markdown files directly.
- *Extensible and Future-Proof:* Built on modern static frameworks, it
natively supports *MDX*, meaning rich interactive elements, quizzes,
or microlearning blocks can be coded directly into the text when needed. It
easily accommodates GraphQL API document renderers, saves articles as pure
text files that can easily be mapped to *MCP* configurations for AI
assistants, and eliminates standard licensing concerns.
Consequences Positive Impacts
- Completely serverless structure means zero server hosting expenses
or maintenance.
- Complete alignment with Git workflows: edits from non-technical
staff trigger Pull Requests or direct commits, keeping the documentation
tightly coupled with platform versioning.
- Fully localized full-text search works completely offline as part of
the client bundle if local index plugins are used.
- Unrestricted ability to inject lightweight, privacy-focused,
cookie-free analytics tracking scripts (such as Plausible or Matomo).
Negative Impacts / Risks
- Setting up the initial data schemas for the visual CMS and custom
components requires up-front developer engineering hours.
- Compiling massive amounts of media content locally may slow down
CI/CD build pipelines slightly over time, requiring asset optimization.
—
Reply to this email directly, view it on GitHub
<#2740?email_source=notifications&email_token=ABP2BFBIKUTRLNJ2MW3P23D47AWTHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINRWGE2DMOBXHE3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4661468796>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABP2BFATIMH2IRRLGGQ47TL47AWTHAVCNFSM6AAAAACZQRSCUCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DMNRRGQ3DQNZZGY>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
Member
|
Actually, I see that Github AI is out of credits - if you're using that for
this I'm not sure how efficient it is since it doesn't have the quality
prompts I usually require in this type of analysis.
In that case I'd like to hear from you what's the benefit of using a
solution like docusaurus over fully replacing it with something like
genially, HSP5 or authorship tool. What is the point of building
integrations on top of integrations when you can just have one solution?
…On Wed, Jun 10, 2026, 8:45 AM Roanna Kong ***@***.***> wrote:
Philipp, can you explicitly ask Claude and Gemini to evaluate vs the
learning authorship tools I shared, and tell it to heavily weight my
initial feedback, especially my revised problem statement? It's currently
over weighting your original formulation (I think bc you ask it not to
change code) but you should tell it to consider the original formulation as
exploratory, and my feedback as primary since I'm product owner / HoP.
This revision is not very good and is just regurgitating previous work
such as Mauro's PR. I'd also like you to add some human thinking Philipp
since this revision is not as good as what I've previously seen from you.
On Tue, Jun 9, 2026, 11:54 PM Philipp Metzner ***@***.***>
wrote:
> *pylipp* left a comment (boxwise/boxtribute#2740)
> <#2740 (comment)>
>
> @aerinsol <https://github.com/aerinsol> while the research for the ADR
> was conducted with Claude, I also ran it against Gemini which votes to go
> for Docusaurus:
> Summary Table of Evaluated Options
> Requirement / Criterion Option 1: GitBook (SaaS Non-Profit) Option 2:
> Docusaurus / Starlight + Git CMS (Tina/Decap) Option 3: Wiki.js
> (Self-Hosted OSS) Option 4: Headless CMS (Directus) + Next.js Frontend
> *Financial Cost* Free (via OSS/Non-profit tier) Free (Open source, free
> static hosting) Free (Open source software) Free (Open source software)
> *Non-Tech Editing* *Excellent* (Intuitive WYSIWYG visual editor) *Good*
> (Visual/form web-UI commits to Git in backend) *High* (Built-in rich
> text & Markdown editor editors) *Excellent* (Highly tailorable content
> block layouts)
> *Offline / PWA* *Poor* (No native service worker/offline browsing
> support) *Excellent* (Native PWA plugins leveraging Workbox caching)
> *Poor* (Lacks built-in deep offline application layer) *Excellent* (Can
> configure custom next-pwa service workers)
> *Search* *Excellent* (Built-in AI-powered instant search) *Excellent*
> (Algolia DocSearch or local search plugins) *Good* (Built-in DB search
> or Elasticsearch) *Custom* (Requires manual integration with a search
> engine)
> *Theming* *Medium* (Basic layout customization, colors, logo) *Excellent*
> (Full CSS/React framework design control) *Medium* (Theme variables and
> injected custom CSS) *Excellent* (Unrestricted frontend layout control)
> *Custom Domain* *Yes* (Included in baseline community tiers) *Yes* (Free
> configuration via static hosts) *Yes* (Configured via web reverse proxy)
> *Yes* (Handled directly at the frontend deployment layer)
> *Interactivity* *Medium* (Standard tabs, hints, embeds) *Excellent* (MDX
> allows embedding custom React logic) *Medium* (Standard HTML widgets)
> *Excellent* (Full freedom to build custom learning applications)
> *Analytics* *Good* (Supports third-party script integrations) *Excellent*
> (Easy plugin script injection for Plausible) *Good* (Global script
> insertion in configuration panel) *Excellent* (Custom telemetry
> implementation)
> *Self-Hosted Burden* *None* (Fully managed SaaS platform) *Very Low*
> (Serverless execution, zero ongoing ops maintenance) *Medium* (Requires
> hosting Node.js and PostgreSQL containers) *High* (Requires maintaining
> CMS engine, DB, and frontend)
> *Time to Set Up* *Very Low* (Immediate onboarding and setup) *Medium*
> (Initial repository layout and CMS schema configuration) *Low-Medium*
> (Server deployment and container provisioning) *High* (Full architecture
> definitions, data mapping, and coding)
> ------------------------------
> Decision Outcome Chosen Option: Option 2 (Docusaurus / Starlight +
> Git-Backed Visual CMS like TinaCMS) Justification
>
> Option 2 strikes the ideal balance between Boxtribute's strict core
> philosophy (*Reliability > Sexiness*, *Minimal maintenance*, and *Keep
> it simple*) and the complex requirements of field deployment.
>
> - *Zero Server Overhead:* Because it compiles directly down to static
> assets, it can be hosted for free on serverless infrastructure (e.g.,
> GitHub Pages, Cloudflare Pages, Netlify), requiring no server maintenance,
> zero database updates, and removing security patching vectors from the
> engineering team.
> - *Critical Offline Caching:* Unlike GitBook or Wiki.js, Option 2
> natively supports robust PWA capabilities via Workbox plugins. This allows
> aid workers and operators inside low-connectivity refugee camps to reliably
> view documentation and training guides on-demand after their initial visit.
> - *Empowered Non-Tech Contribution:* Integrating a Git-backed CMS
> (such as TinaCMS or Decap CMS) gives the operations and partnerships teams
> a clean, visual web interface to draft and publish changes without needing
> to understand Git, terminal commands, or Markdown files directly.
> - *Extensible and Future-Proof:* Built on modern static frameworks,
> it natively supports *MDX*, meaning rich interactive elements,
> quizzes, or microlearning blocks can be coded directly into the text when
> needed. It easily accommodates GraphQL API document renderers, saves
> articles as pure text files that can easily be mapped to *MCP*
> configurations for AI assistants, and eliminates standard licensing
> concerns.
>
> Consequences Positive Impacts
>
> - Completely serverless structure means zero server hosting expenses
> or maintenance.
> - Complete alignment with Git workflows: edits from non-technical
> staff trigger Pull Requests or direct commits, keeping the documentation
> tightly coupled with platform versioning.
> - Fully localized full-text search works completely offline as part
> of the client bundle if local index plugins are used.
> - Unrestricted ability to inject lightweight, privacy-focused,
> cookie-free analytics tracking scripts (such as Plausible or Matomo).
>
> Negative Impacts / Risks
>
> - Setting up the initial data schemas for the visual CMS and custom
> components requires up-front developer engineering hours.
> - Compiling massive amounts of media content locally may slow down
> CI/CD build pipelines slightly over time, requiring asset optimization.
>
> —
> Reply to this email directly, view it on GitHub
> <#2740?email_source=notifications&email_token=ABP2BFBIKUTRLNJ2MW3P23D47AWTHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINRWGE2DMOBXHE3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4661468796>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/ABP2BFATIMH2IRRLGGQ47TL47AWTHAVCNFSM6AAAAACZQRSCUCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DMNRRGQ3DQNZZGY>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>
|
Contributor
@aerinsol I had started a fresh agent session with the updated problem statement; without hinting at any possible tools. Where did you see the exhausted AI credits?
I'm looking into that, I guess the docusaurus integrations come from an OSS/community-driven philosophy that wants to focus on modularity instead of providing a monolithic (closed-source) solution. |
Member
|
I forwarded you the notice, it was sent to billing. I do think dependency is an issue, however, if text export and SCORM / xAPI (what big Corp systems use) are there this is somewhat mitigated. I'd actually day building a lot of custom OSS tooling can be more difficult to maintain - unless we want to commit to maintaining that long term - possible but should be explicitly evaluated rather than jumping to conclusions. Re: new agent session - yes, but most tools these days can read context from other sessions and will make assumptions. Unfortunately I'm behind the GFW and can't send you my context. In any case please challenge the assumptions, ask it to cite sources and cross reference if you can. |
[skip ci]
[skip ci]
pylipp
force-pushed
the
copilot/create-adr-for-documentation-options
branch
from
7c86251 to
1a31787
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Boxtribute needs a public documentation site for FAQs, guides, and best practices—accessible to aid workers in low-connectivity environments.
ADR Summary
Evaluated 14 options against requirements: free/OSS, offline/PWA caching, search, theming, non-tech editing, custom domain, blog support.
Options Evaluated
Key Findings
GitBook Community plan is more capable than initially reported (includes custom domains + analytics), but lacks offline support—critical for field teams.
Recommendation
Docusaurus — meets all must-haves, aligns with React stack, has GraphQL docs plugin (
@graphql-markdown/docusaurus) and MCP integration (docusaurus-plugin-mcp-server). Deploy on Vercel with Plausible analytics.