Obsidian Audit

Observed Behavior: The Download page auto-detects the user’s operating system and highlights the appropriate download button. On several Linux distributions (Ubuntu 22.04 in Firefox, Fedora 39 in Chrome), the detection fails and defaults to “macOS,” offering the wrong installer.

Technical Root Cause: The platform detection relies on navigator.platform, which has been deprecated and returns inconsistent values across Linux distributions and browsers. The fallback logic assumes macOS when the string doesn’t match a known Windows pattern.

Business Impact: Linux users are a disproportionately important segment for Obsidian (developers, researchers, privacy-conscious users). Serving them the wrong download link creates friction at the exact moment of conversion and pushes them toward community-maintained package managers (Flatpak, Snap) where Obsidian has less control over the update experience.

Remediation Path: Replace navigator.platform with navigator.userAgentData.platform (with a User-Agent string fallback). Detect Linux explicitly and present .AppImage, .deb, .rpm, and Snap options with brief guidance on which format to choose. When in doubt, show all platform options rather than guessing wrong.

Observed Behavior: The interactive graph visualization on the homepage runs continuously even when the user has scrolled past it. On mid-range devices (e.g., M1 MacBook Air with 20+ browser tabs), scrolling the page becomes noticeably choppy while the graph animation consumes CPU in the background.

Technical Root Cause: The D3-force physics simulation driving the graph runs on every requestAnimationFrame tick regardless of whether the canvas is visible in the viewport. The simulation never pauses or enters a “cooled” state.

Business Impact: Users browsing the rest of the homepage experience degraded scroll performance, which they attribute to the site being poorly built — damaging the first impression of a tool that sells itself on responsiveness and speed.

Remediation Path: Use an Intersection Observer to pause the D3 simulation (simulation.stop()) when the graph canvas exits the viewport. Resume (simulation.restart()) only when the canvas re-enters. Additionally, cap the simulation’s alpha decay so it converges to a stable layout within 3-4 seconds, after which it can fully stop until the user interacts.

Observed Behavior: The Pricing page has a “Monthly / Annual” billing toggle. Selecting “Annual” pricing and then navigating to another page and back (via browser back button) resets the toggle to “Monthly,” forcing the user to re-select their preferred billing cadence.

Technical Root Cause: The toggle state is stored in local component state (likely useState in React or a vanilla JS variable) and is not persisted to the URL hash, query parameter, or sessionStorage.

Business Impact: Users comparing plans across multiple tabs or returning to verify pricing see the higher monthly price instead of the annual price they already chose, creating sticker shock and eroding the momentum toward purchase.

Remediation Path: Sync the billing toggle state to a URL query parameter (?billing=annual). This preserves the selection across navigation, enables deep linking to annual pricing from blog posts or emails, and ensures the back button restores the user’s intended view.

Observed Behavior: The search function on help.obsidian.md occasionally returns results linking to pages that have been moved or renamed, resulting in 404 errors when clicked.

Technical Root Cause: The client-side search index (likely a pre-built Lunr or Fuse.js index file) is generated at build time but is aggressively cached by the CDN. When documentation is updated and pages are restructured, the stale index continues to serve old URLs until the cache TTL expires.

Business Impact: Users searching for help on critical topics (e.g., “sync conflict resolution”) land on 404 pages, which is especially frustrating when they are troubleshooting an active issue with a paid service.

Remediation Path: Version the search index filename with a content hash (e.g., search-index.a3f8b2.json) so that CDN cache busting is automatic on every deploy. Implement a redirect map for recently moved pages so that stale URLs resolve gracefully instead of 404-ing.

Observed Behavior: The homepage hero uses phrases like “A second brain, for you, forever” and immediately dives into “backlinks,” “graph view,” and “local-first” without defining these terms. The first section below the fold references “Zettelkasten” and “networked thought” — concepts that require significant prior knowledge.

Technical Root Cause: The marketing copy was written by and for the existing community of personal knowledge management (PKM) enthusiasts, not for the mainstream user who searches for “best note-taking app” and arrives with no context.

Business Impact: Visitors from mainstream channels (Google, YouTube reviews, Reddit recommendations) bounce because the value proposition is unclear. They understand “take notes” but not “build a second brain.” This caps Obsidian’s addressable market at the PKM niche rather than the broader productivity market.

Remediation Path: Lead the homepage with a concrete, benefits-first message: “Write notes that you own. Link them together. Find anything instantly.” Defer the PKM philosophy to a secondary section labeled “Built on proven principles” where Zettelkasten and networked thought can be explained with visual examples. A/B test the simplified hero against the current version.

Observed Behavior: The Community Plugins directory presents 1,500+ plugins in a single, alphabetically sorted list with only a search bar for discovery. Users who don’t know what they’re looking for (e.g., “I want to manage tasks in Obsidian”) have no way to browse by category.

Technical Root Cause: The plugin directory was built as a minimal search interface, pulling directly from the community plugin registry without layering a taxonomy or curated categories on top of it.

Business Impact: Plugins are a primary driver of Obsidian’s stickiness and a key differentiator from competitors. If users cannot discover relevant plugins, they are less likely to build the deep workflows that lead to Sync and Publish subscriptions.

Remediation Path: Implement category tags (e.g., “Task Management,” “Writing,” “Academic Research,” “Daily Notes,” “Visual/Canvas”) and a curated “Staff Picks” or “Essential Plugins” section at the top of the directory. Allow filtering by category, download count, and last-updated date.

Observed Behavior: The Obsidian Publish page describes the feature in text and shows a few static screenshots but does not include a single clickable example of a live Publish site. The user must take the product description on faith.

Technical Root Cause: The Publish page was built as a traditional feature-marketing page rather than a showcase. There is no curated gallery of community Publish sites to demonstrate the output quality.

Business Impact: Publish costs $8/month — a premium for a personal publishing tool. Without seeing live examples of beautiful, functional Publish sites, potential buyers cannot envision the result and are unwilling to pay before they see proof of quality.

Remediation Path: Add a “See what people have built” gallery showcasing 6-8 high-quality community Publish sites across categories (developer blog, research wiki, digital garden, course notes). Include screenshots with live links. Feature these examples prominently above the pricing CTA.

Observed Behavior: On mobile viewports, opening the Help documentation sidebar navigation overlays the content area with a semi-transparent backdrop, but tapping a link in the sidebar does not auto-close it. The user must manually dismiss the sidebar to read the article they just navigated to.

Technical Root Cause: The sidebar’s click handler navigates to the new page but does not toggle the isOpen state of the mobile menu component. The sidebar remains visible over the new content.

Business Impact: Users reading documentation on their phones — often while troubleshooting an Obsidian issue on their desktop — are stuck in a loop of opening and manually closing the sidebar for each article, degrading the support experience.

Remediation Path: Auto-close the mobile sidebar after any navigation link is clicked. Listen for route change events (or popstate if using static pages) and set isOpen = false on navigation.

Observed Behavior: The homepage and Download page focus exclusively on the free desktop app. Obsidian Sync — the company’s primary revenue driver — is mentioned only on the Pricing page and in a small footer link. A user who downloads the app and sets it up on their laptop has no exposure to Sync’s existence.

Technical Root Cause: The site architecture treats “acquire free users” and “monetize via Sync” as separate, sequential funnels rather than an integrated journey. The assumption is that users will discover Sync organically through the app’s settings.

Business Impact: Users who need cross-device syncing default to iCloud, Google Drive, or Dropbox workarounds — all of which have known conflict issues with Obsidian vaults — and never realize that an official, end-to-end encrypted solution exists. Revenue is lost to workarounds.

Remediation Path: Add a “Works across all your devices” section on the homepage that introduces Sync in the context of the benefit (not the paid product). After a user clicks “Download,” show a post-download interstitial: “While your download completes: keep your vault synced across Mac, iPhone, and iPad with Obsidian Sync.” This surfaces the upsell at the moment of highest engagement without interrupting the free download.

Observed Behavior: The Pricing page lists Sync features (end-to-end encryption, version history, selective sync) but does not address why a user should pay $4/month instead of using free cloud storage services that also sync files.

Technical Root Cause: The pricing copy assumes users understand the technical limitations of generic file sync (merge conflicts, no version history, no end-to-end encryption for markdown files). It does not directly compare Sync against the alternatives users are already using.

Business Impact: The most common objection to Sync is “I already use iCloud/Dropbox for free.” Without directly answering this objection on the pricing page, users self-select out of the paid funnel.

Remediation Path: Add a comparison table directly on the Pricing page: “Obsidian Sync vs. iCloud / Dropbox / Google Drive.” Columns: conflict resolution, end-to-end encryption, version history (granular vs. file-level), selective folder sync, speed. This reframes the conversation from “free vs. paid” to “reliable vs. fragile.”

Observed Behavior: The homepage presents a single, undifferentiated value proposition. There are no dedicated landing pages for Obsidian’s distinct user segments: software developers (who care about Git integration, code blocks, and plugin APIs), academic researchers (who care about citations, Zotero integration, and PDF annotation), or writers (who care about distraction-free writing and Publish).

Technical Root Cause: The marketing strategy relies on the community to self-segment and discover Obsidian’s relevance through forums, YouTube videos, and blog posts, rather than creating targeted entry points.

Business Impact: Users arriving from a Google search for “best note-taking app for developers” or “academic research tool” land on a generic homepage that does not speak to their specific workflow. They bounce to competitor pages (Notion for Teams, Logseq for Researchers) that address their use case directly.

Remediation Path: Create 3-4 use-case landing pages: “Obsidian for Developers,” “Obsidian for Researchers,” “Obsidian for Writers.” Each page should showcase relevant community plugins, vault templates, and workflows. Target these pages at segment-specific search queries.

Observed Behavior: Obsidian Sync offers a discount for annual billing, but the pricing page defaults to showing the monthly price. The annual option is accessed via a small toggle that most users will not notice.

Technical Root Cause: The pricing page design gives equal visual weight to both billing options, and the toggle is styled as a subtle UI element rather than a persuasive call-out.

Business Impact: Users who would prefer to commit annually at a lower per-month rate default to monthly billing because they never see the savings. Annual plans have significantly lower churn rates, making this a double loss: less revenue per user and higher monthly churn.

Remediation Path: Default the pricing toggle to “Annual” and add a visible savings badge (e.g., “Save 17% with annual billing”). Display the annual price prominently with the monthly equivalent in smaller text below: “$48/year ($4/mo).” Consider offering a first-year discount to incentivize the annual commitment.

Observed Behavior: Over 60% of help.obsidian.md pages lack a custom <meta name="description"> tag. Google auto-generates snippets from the first paragraph, which often pulls sidebar navigation text or breadcrumb labels rather than useful content summaries.

Technical Root Cause: The static site generator (likely a Hugo or Eleventy-based docs system) does not enforce a description field in each page’s markdown frontmatter, and no fallback extraction logic is in place.

Business Impact: Help documentation pages rank for thousands of long-tail queries (“how to use backlinks in Obsidian,” “Obsidian sync setup guide”), but the auto-generated snippets are unhelpful. Users see confusing previews in Google and click on third-party blog tutorials instead of the official docs, losing traffic and brand authority.

Remediation Path: Add a description field to the frontmatter of every help doc page. For pages without a manual description, implement a build-time script that extracts the first 150 characters of the first body paragraph (excluding headers and code blocks) as the fallback meta description.

Observed Behavior: The 1,500+ community plugin pages in the directory are rendered client-side via JavaScript. Viewing the page source shows an empty <div id="root"> with no pre-rendered content. Googlebot’s JavaScript rendering budget means many plugin pages are never indexed.

Technical Root Cause: The plugin directory is a single-page application (SPA) that fetches plugin data from the community registry API at runtime. There is no server-side rendering (SSR) or static site generation (SSG) for individual plugin pages.

Business Impact: Obsidian misses thousands of long-tail search queries like “Kanban board plugin for Obsidian,” “Obsidian Zotero integration,” and “calendar plugin Obsidian.” These are high-intent queries from users already evaluating Obsidian or seeking to extend their setup.

Remediation Path: Pre-render individual plugin pages as static HTML at build time using data from the community plugin registry. Generate pages at routes like /plugins/kanban, /plugins/dataview, etc. Include the plugin name, description, author, download count, and last-updated date in the HTML. Add SoftwareApplication JSON-LD schema to each page.

Observed Behavior: The obsidian.md homepage transfers 3.8MB on initial load, primarily from large PNG screenshots (800KB+), an uncompressed hero video, and the D3 graph visualization JavaScript bundle. Largest Contentful Paint (LCP) measures 3.9 seconds on a 4G connection.

Technical Root Cause: The asset pipeline does not include image compression, WebP/AVIF conversion, or responsive srcset generation. The video is served without a compressed poster frame. The D3 library is bundled at full size without tree-shaking.

Business Impact: LCP above 2.5 seconds is rated “Needs Improvement” by Google, directly reducing the homepage’s ranking potential for high-volume queries like “Obsidian note-taking app” and “best markdown note app.”

Remediation Path: Convert all PNG screenshots to WebP with responsive srcset breakpoints. Add a poster frame to the hero video and lazy-load the video itself below the fold. Tree-shake the D3 bundle to include only d3-force, d3-selection, and d3-zoom — approximately 30% of the full library.

Observed Behavior: The Pricing page has no JSON-LD structured data. Google cannot parse the pricing tiers, product names (Sync, Publish, Commercial License), or billing options in a machine-readable format.

Technical Root Cause: Structured data was not included in the site’s original build, and the Pricing page template does not inject any JSON-LD scripts.

Business Impact: When users search “Obsidian Sync pricing” or “Obsidian Publish cost,” Google cannot display rich pricing information in the SERP. Competitors with structured pricing data (Notion, Roam) may display prices directly in search results, capturing attention before Obsidian.

Remediation Path: Add Product JSON-LD schema for each paid offering (Sync, Publish, Commercial License) with name, description, and offers (including price, priceCurrency, and availability). Add SoftwareApplication schema to the homepage with links to the pricing page.