Properties4
1Lithos transforms your Obsidian vault into a production-ready documentation website powered by Nuxt and Docus. Whether you're documenting a software project, building a digital garden, or creating a knowledge base, Lithos preserves your Obsidian workflow while delivering a polished web experience. This guide will walk you through installation, project structure, and creating your first pages.
Prerequisites and Installation
Before you begin, ensure your development environment meets the necessary requirements. Lithos is built on modern web technologies and requires specific versions to function correctly.
System Requirements
You'll need Node.js version 20 or higher installed on your system. This is the runtime environment that powers Nuxt 4, the framework underlying Lithos. You can verify your Node.js version by running node --version in your terminal. If you need to install or upgrade Node.js, visit the official Node.js website or use a version manager like nvm to ensure you have the latest LTS release.
Basic terminal knowledge is helpful for running installation commands and starting the development server. You don't need to be a command-line expert, but familiarity with navigating directories and executing scripts will make the process smoother. If you're comfortable installing npm packages and running development servers for other JavaScript projects, you're well-prepared.
An existing Obsidian vault is recommended but not required. If you're starting from scratch, Lithos includes sample content to help you understand the structure. However, the real power of Lithos shines when you connect it to an existing vault full of interconnected notes, allowing you to instantly transform months or years of knowledge work into a navigable website.
Installation Steps
Start by cloning the Lithos repository to your local machine. Open your terminal and navigate to the directory where you want to store the project. Run git clone https://github.com/jwintz/lithos.git to download the source code. Once the clone operation completes, navigate into the newly created lithos directory with cd lithos.
Next, install the project dependencies using npm. Execute npm install in the terminal, which will download all required packages including Nuxt, Docus, and Lithos-specific modules. This process may take a few minutes depending on your internet connection and system performance. The installation includes everything from the core framework to specialized plugins for Obsidian syntax transformation, graph visualization, and mathematical notation rendering.
The final installation step is connecting your Obsidian vault. Lithos expects your content to live in a content/ directory, but rather than duplicating your vault, you'll create a symbolic link. This approach ensures that changes you make in Obsidian are immediately reflected in the development server without manual copying. If you have an existing vault at ~/Documents/MyVault, run ln -s ~/Documents/MyVault content from the Lithos project directory. On Windows, use mklink /D content C:\Path\To\MyVault instead.
Running the Development Server
With installation complete, you're ready to see your documentation site in action. Start the development server by running npm run dev in your terminal. Nuxt will compile your site and make it available at http://localhost:3000. The first launch takes longer as Nuxt builds the application and indexes your content, but subsequent starts are much faster thanks to caching.
Open your web browser and navigate to localhost:3000. You should see your documentation site with navigation automatically generated from your vault's folder structure. The development server includes hot module replacement, meaning changes you make to your markdown files in Obsidian will automatically refresh in the browser without needing to restart the server.
Maintenance and Cleanup
As you work on your documentation, Lithos maintains various caches to improve build performance. If you encounter persistent rendering issues or want to ensure a completely fresh build, you can use the cleanup command:
npm run cleanup
This command removes all build caches and output directories, including:
.output/: The generated static site.data/: Nuxt Content's SQLite database.nuxt/: Nuxt's build artifactsnode_modules/.cache/nuxt/: Cached module data
It is recommended to run a cleanup before generating a final production build to ensure that no stale data persists from previous development sessions.
If you encounter errors during startup, check that your symlink was created correctly and that your vault doesn't contain syntax errors in frontmatter. The terminal will display helpful error messages indicating which files have issues. Most problems stem from malformed YAML in frontmatter blocks or unsupported characters in filenames.
Understanding the Project Structure
Lithos organizes code and content into distinct directories, each serving a specific purpose. Understanding this structure helps you customize the site and troubleshoot issues effectively.
Core Directories
The vault/ directory (or whatever you named your symlinked Obsidian vault) contains all your markdown content. This is your single source of truth. Every note, image, and attachment in this directory becomes part of your documentation site. Lithos respects Obsidian's folder structure, converting it into a hierarchical navigation menu. Files prefixed with numbers like 1.guide/ are automatically ordered, with the numeric prefix stripped from URLs and display names.
The modules/ directory contains custom Nuxt modules that power Lithos's Obsidian compatibility. You'll find obsidian-transform.ts which converts wikilinks to standard links, obsidian-bases.ts which processes database queries, obsidian-graph.ts which generates graph data, and obsidian-ordering.ts which handles numbered file prefixes. These modules run during the build process, transforming your Obsidian syntax into web-compatible HTML before the page reaches the browser.
The components/ directory houses Vue components used throughout the site. Global components like ObsidianCallout.vue, ObsidianBase.vue, and GraphVisualizer.vue are automatically available in your markdown files using MDC syntax. You can create custom components here to extend Lithos with specialized functionality like interactive demos, data visualizations, or custom navigation widgets.
Configuration Files
The nuxt.config.ts file is the central configuration for your Lithos site. It defines content ignore patterns (to exclude .obsidian folders), remark and rehype plugins for markdown processing, CSS imports, and pre-rendering rules for static site generation. Most users won't need to modify this file, but it's where you'd adjust advanced settings like custom remark plugins or deployment-specific route rules.
The app.config.ts file controls theme and UI customization. Here you'll set your site title, choose color schemes (Lithos defaults to violet primary and zinc neutrals), and override component styles. This is the first file to edit when branding your documentation site with custom colors, fonts, or layout tweaks.
The pages/ directory defines special routes that aren't part of your regular documentation. For example, pages/graph.vue renders the interactive knowledge graph, and pages/index.vue serves as a custom landing page if you don't have an index.md in your vault. You typically won't need to modify these unless you're adding entirely new page types beyond documentation.
Creating Your First Pages
With Lithos running, you're ready to create content. The beauty of this workflow is that you continue working in Obsidian exactly as you normally would, and Lithos handles the transformation automatically.
Writing Your First Note
Open Obsidian and navigate to your vault (the one you symlinked to Lithos). Create a new note called "Welcome.md" in the root of your vault. Add a YAML frontmatter block at the very top of the file. Frontmatter provides metadata that Lithos uses for navigation, SEO, and styling. A minimal frontmatter block looks like this:
---
title: Welcome to My Docs
description: An introduction to this documentation site.
icon: i-lucide-home
---
Below the frontmatter, write standard markdown content. Use headings to structure your page, with ## for main sections and ### for subsections. Add paragraphs, lists, code blocks, and images just as you would in any Obsidian note. The key difference is that Lithos will render these elements with professional styling and responsive design.
Save the file in Obsidian and switch to your browser. The development server will detect the change and refresh the page automatically. You should see "Welcome" appear in the navigation sidebar, and clicking it will display your content with Docus's clean documentation theme applied.
Understanding Frontmatter
Frontmatter is the bridge between Obsidian and web presentation. The title field overrides the filename as the page's display title, allowing you to use concise filenames while showing full, descriptive titles to readers. The description field appears in search engine results and page previews, making it crucial for SEO and social media sharing.
The icon field accepts Lucide icon identifiers in the format i-lucide-icon-name. These icons appear in the navigation sidebar next to page titles, providing visual cues that help readers quickly scan the navigation. The order field controls where the page appears in the sidebar relative to siblings, with lower numbers appearing first. Use navigation.icon to override the icon specifically for the sidebar if you want a different icon in the page header.
Tags help organize content across multiple dimensions. Add tags: [tutorial, beginner, setup] to your frontmatter, and you can later create database views that filter by these tags. Tags are particularly powerful when combined with Structured Data queries that dynamically list pages matching certain criteria.
Connecting Pages with Wikilinks
The real power of Obsidian shines when you start linking notes together. Create a second note called "Getting Help.md" with similar frontmatter. In your Welcome note, add a reference like For more information, see [[Getting Help]]. When you save and view the page, Lithos automatically converts this wikilink into a proper hyperlink that navigates to the Getting Help page.
Wikilinks work with aliases too. If you want the link text to differ from the page title, use the pipe syntax: [[Getting Help|support documentation]]. This renders as "support documentation" but links to the Getting Help page. Lithos resolves these links at build time, so broken links are caught before deployment rather than frustrating your readers with 404 errors.
You can link to specific sections within a page using heading anchors. The syntax [[Getting Help#Troubleshooting]] creates a link that scrolls directly to the Troubleshooting heading when clicked. This is invaluable for directing readers to precise information within longer pages, and it works seamlessly with Lithos's automatic anchor generation.
Connecting an Existing Vault
If you're bringing an established Obsidian vault to Lithos, there are a few considerations to ensure a smooth transition. Most vaults work out of the box, but understanding how Lithos handles special folders and files helps avoid surprises.
Vault Structure Mapping
Your vault's folder hierarchy becomes your documentation site's navigation structure. A folder named Guides in your vault becomes a top-level navigation section called "Guides" on the website. Nested folders create nested navigation sections. Lithos automatically generates an index page for each folder if one doesn't exist, displaying a list of child pages.
Files prefixed with numbers like 1.Introduction.md or 2.Setup.md are automatically ordered in the sidebar according to their numeric prefix. Lithos strips the numbers from URLs and display titles, so 1.Introduction.md becomes accessible at /introduction and displays as "Introduction" in navigation. This numbering system gives you precise control over page order without cluttering URLs or titles.
Index files deserve special attention. If a folder contains an index.md file, that file's content becomes the landing page when someone clicks on the folder in navigation. This is perfect for overview pages that introduce a section before diving into specific topics. If no index file exists, Lithos generates a simple directory listing instead.
Handling the .obsidian Folder
Your vault's .obsidian folder contains Obsidian-specific configuration and cache files that have no place in a public documentation site. Lithos automatically excludes this folder from content processing using ignore patterns in nuxt.config.ts. You don't need to delete or move the folder—it simply won't appear in the generated site.
The same applies to .trash, .git, and other hidden folders. Lithos's default ignore patterns catch common system and tool-specific directories, ensuring only your actual content is published. If you have custom folders that should be excluded, you can add them to the content.ignores array in nuxt.config.ts.
Daily notes folders often contain hundreds of chronological entries that might not belong in standard documentation navigation. Lithos provides special handling for daily notes, which you can learn about in the Daily Notes feature documentation. The key insight is that you have full control over what gets published versus what stays private to your vault.
Obsidian Plugins and Compatibility
Lithos natively supports core Obsidian syntax including wikilinks, embeds, callouts, and frontmatter. Most community plugins that add markdown extensions work seamlessly because they produce standard markdown that Lithos can process. However, plugins that rely on Obsidian's desktop app features (like calendar integrations or file tree modifications) won't have equivalents in the web version.
Dataview queries are not directly supported, but Lithos offers an alternative through Structured Data (Obsidian Bases). These database views use a similar query syntax but are optimized for static site generation. You'll need to convert complex Dataview queries to Bases syntax, but the result is faster and more maintainable for web deployment.
Canvas files and other binary plugin formats won't render on the website. Lithos focuses on markdown content, so if your workflow heavily relies on visual canvases or specialized plugin data formats, consider how to represent that information in markdown for public consumption. Many users maintain separate "public" and "private" sections within their vault, using frontmatter tags to control what gets published.