Document Tools¶
Evaluation of documentation generators and note/vault tooling for BNI's profile: a non-profit with a mixed technical + management audience, open source, Markdown as source of truth, needing graphics and polish.
Documentation site generator¶
Recommendation: MkDocs + Material theme¶
The strongest fit, and not a close call. Fully open source (MkDocs core and Material theme both MIT; Material's "Insiders" tier is optional and not needed). You write pure Markdown and get a polished, fast, searchable static site. Hosting is free on GitHub Pages, GitLab Pages, Netlify, or Cloudflare Pages — which matters on a non-profit budget. (This is the generator BNI's own docs site runs on.)
Out of the box: full-text client-side search, dark/light mode, responsive sectioned/tabbed navigation, code syntax highlighting, admonitions, tabbed content, footnotes, math (MathJax/KaTeX), and native Mermaid diagram rendering — so org charts, process flows, funding pipelines, and theory-of-change diagrams all render from text.
Supporting stack: Git repo of .md files + mkdocs.yml; Mermaid for text-based diagrams, draw.io / diagrams.net (open source) for richer SVGs; images under docs/assets/; CI (e.g. GitHub Actions) building on push; mkdocs-with-pdf or mkdocs-print-site-plugin for PDF deliverables from the same source. One Markdown corpus produces both site and PDFs.
Alternatives considered¶
| Tool | Verdict |
|---|---|
| Docusaurus | Excellent but heavier (React-based, developer-oriented). Worth it for versioned docs (v1.0/v2.0) or a tightly integrated blog; otherwise overkill. |
| GitBook | Free OSS tier, but polished collaboration is paid and the self-hosted gitbook-cli is deprecated. Not a good long-term bet. |
| Wiki.js / BookStack | Good and open source, but database-backed CMSs — you lose the "edit a file in Git, push, site updates" flow. |
| Quarto | Impressive (one source → website, PDF, slides, Word) and fully OSS, but optimized for data/scientific publishing. Material gives a more polished business-docs result with less config. |
Note / vault tooling — open-source alternatives to Obsidian¶
Obsidian is free but not open source (proprietary core, open plugin ecosystem). The truly open-source analogs:
Closest analogs
- Logseq (AGPL) — most popular OSS alternative. Local-first, stores Markdown/Org-mode in a folder you control. Outliner-based (block-level references) rather than page-based. Bidirectional links, backlinks, graph view, daily notes, queries, plugins.
- SilverBullet (MIT) — newer, self-hostable web app (browser-based, syncs files to your server). Markdown-native
[[wiki links]], a live query language, Lua plugins. Good for a vault reachable from any device without per-device installs. - AppFlowy (GPL/AGPL) — more a Notion alternative (page-based, database views, kanban) but supports Markdown and linked pages.
Lighter-weight Markdown editors with some linking
- Joplin (MIT/AGPL) — mature; Markdown, attachments, E2E-encrypted sync, tags. Note links but no full backlinks/graph.
- Zettlr (GPL) — academic focus: citations, footnotes, Pandoc export,
[[wiki links]], basic backlinks. - MarkText / Ghostwriter — pure Markdown editors, no linking/vault features.
VS Code as a vault
The Foam extension (MIT) turns a folder of Markdown files into an Obsidian-like vault ([[wiki links]], backlinks, graph, daily notes). The key advantage: the same folder also serves as MkDocs source, so note-taking and documentation become the same activity on the same files — no duplication, no sync. Markdown Memo and Dendron are similar (Dendron more hierarchical).
Practical recommendation for BNI¶
| Scenario | Recommendation |
|---|---|
| Mixed technical/non-technical team, one consistent tool | Logseq for everyone + MkDocs reading the same folder |
| Contributors mostly comfortable in VS Code | Foam in VS Code — same files, folder, and Git repo as the MkDocs site |
| Web-based vault accessible from any browser without installs | SilverBullet, self-hosted on a small VPS or container |