Writing Content

You write content in Obsidian using familiar Obsidian syntax. Lithos transforms everything at build time into web-ready HTML. You do not need to learn a new syntax -- your vault stays native Obsidian and the transformer handles the rest.

Supported Obsidian Syntax

The following Obsidian features are fully supported by Lithos:

Obsidian features that are not yet supported: Dataview queries, block references (^block-id), comments (%%), Canvas (planned).

Standard Markdown Support

Lithos supports the full CommonMark specification plus GitHub Flavored Markdown extensions. This foundation ensures compatibility with existing markdown content while providing the features modern documentation demands.

Headings and Structure

Use headings to create a clear content hierarchy. Lithos automatically generates a table of contents from your headings, so consistent heading levels improve navigation. Level 2 headings (##) mark major sections, level 3 headings (###) denote subsections, and level 4 headings (####) provide further detail. Avoid skipping levels—don't jump from ## to ####—as this confuses both readers and accessibility tools.

The frontmatter title field becomes the page's H1 heading, so never start your content with a single # heading. Begin with ## for your first section. This convention keeps the document structure clean and ensures the table of contents displays correctly in the sidebar.

Heading text should be descriptive and scannable. Readers often jump to specific sections using the table of contents, so "Installation Steps" is better than "Steps" and "API Authentication" beats "Auth." Good headings serve as mini-summaries of the content that follows, helping readers quickly assess whether a section contains the information they need.

Paragraphs and Text Formatting

Paragraphs are separated by blank lines in markdown. Lithos renders paragraphs with comfortable line spacing and responsive width that adapts to screen size. For optimal readability, keep paragraphs focused on a single idea and aim for 3-5 sentences per paragraph. Long walls of text intimidate readers, while single-sentence paragraphs feel choppy.

Emphasis uses familiar markdown syntax. Single asterisks or underscores create italic text for subtle emphasis, while double asterisks or underscores create bold text for stronger emphasis. Combine them as bold italic for maximum emphasis, though use this sparingly to avoid visual noise. Inline code uses backticks like npm install to distinguish commands and code from prose.

Links connect your documentation to external resources. Standard markdown links use the format [link text](https://example.com), which renders as a clickable hyperlink. External links automatically get an icon indicating they leave your site. For internal documentation links, prefer wikilinks which are easier to write and maintain, but standard markdown links work too if you prefer explicit path control.

Lists and Ordered Content

Unordered lists use hyphens, asterisks, or plus signs as bullet markers. Lithos renders these with consistent styling regardless of which marker you choose, so pick one and stay consistent. Nested lists require indentation—use two spaces or a tab per nesting level. Lists work well for feature enumerations, step-by-step instructions, or collections of related items.

Ordered lists use numbers followed by periods. The actual numbers don't matter—markdown automatically renumbers the list during rendering—but using sequential numbers in your source makes editing easier. Start each item with 1. for simplicity, or use actual sequence numbers if you prefer. Ordered lists suit processes, rankings, or any content where sequence matters.

Task lists combine checkboxes with list items using - [ ] for uncompleted tasks and - [x] for completed ones. While these render as static checkboxes in the documentation (readers can't toggle them), they're excellent for showing requirements checklists, feature completion status, or tutorial progress. The visual distinction between checked and unchecked items communicates state at a glance.

Obsidian Extensions

Lithos fully supports Obsidian's markdown extensions, letting you write documentation using the same syntax you use for personal notes. This compatibility means you can transform an existing vault into public documentation without rewriting your content.

Wikilinks for Internal Navigation

Wikilinks are Obsidian's signature feature and the heart of connected documentation. The basic syntax [[Page Name]] creates a link to another page in your vault. Lithos resolves these links at build time, converting them to proper web URLs. If the target page doesn't exist, the build process warns you, preventing broken links from reaching production.

Aliases let you customize link text without changing the target. The syntax [[Actual Page Name|display text]] shows "display text" to readers while linking to "Actual Page Name." This is crucial for natural prose—you can write "learn about configuring your site" instead of awkwardly forcing the page title into your sentence. Aliases also help when the page title is technical but you want reader-friendly link text.

Section links target specific headings within pages using the hash syntax [[Page Name#Section Heading]]. This creates an anchor link that scrolls directly to that section when clicked. Section links are invaluable for cross-referencing specific information, especially in long reference documentation where you want to point readers to precise details rather than entire pages. Combine aliases with section links as [[Page Name#Section|custom text]] for maximum flexibility.

Embeds and Transclusion

Embeds use the exclamation point prefix ![[Page Name]] to transclude content from another page directly into the current page. This is powerful for reusing content—write once, display many places. When the source content updates, all pages that embed it automatically reflect the changes. This keeps documentation DRY (Don't Repeat Yourself) and ensures consistency across the site.

Image embeds work identically to note embeds. Place images in your vault and reference them with ![[image.png]]. Lithos handles path resolution automatically, so you don't need to worry about relative paths or asset pipelines. The image appears inline at full width by default, with responsive scaling for mobile devices. Supported formats include PNG, JPG, GIF, SVG, and WebP.

Section embeds target specific headings within pages using the hash syntax ![[Page Name#Section Heading]]. This creates an anchor link that transcludes only the content under that specific heading. This is invaluable for pulling in specific parts of larger documents without duplicating content.

Callouts for Information Hierarchy

Callouts (also called admonitions) highlight important information with colored boxes and icons. The syntax starts with a blockquote > followed by [!type] where type is the callout category. Lithos supports all standard Obsidian callout types including note, tip, important, warning, caution, and more. Each type uses a distinct color and icon to communicate urgency and purpose.

> [!note]
> This is a standard note callout. Use it for supplementary information that supports the main content.

> [!tip] Custom Title
> Callouts can have custom titles. Just add text after the type marker.

> [!warning]
> Warning callouts use yellow/orange colors and an alert icon. Perfect for gotchas and potential pitfalls.

Callouts can contain any markdown including lists, code blocks, and even nested callouts. This flexibility makes them suitable for complex explanations that need visual separation from the main content flow. Use callouts sparingly—too many breaks up the reading experience and diminishes their impact. Reserve them for information that truly deserves special attention.

Collapsible callouts use the minus or plus suffix [!note]- or [!note]+ to control default state. Minus makes the callout collapsed by default (readers must click to expand), while plus keeps it expanded with a collapse option. This is useful for optional advanced content, lengthy examples, or troubleshooting sections that most readers can skip. The interactive disclosure pattern keeps pages scannable while preserving depth for those who need it.

MDC Components (Advanced)

MDC (Markdown Components) allows using Vue components directly in markdown. Use MDC only when Obsidian syntax does not cover your needs -- for example, landing page layouts, interactive demos, or custom Vue components that have no Obsidian equivalent.

Component Syntax Basics

Components use the double-colon syntax ::component-name to open and close a component block. Props pass data to components using curly brace notation. String props use quotes like title="My Title", number props are unquoted like count=5, and boolean props can be bare like dismissible (implies true) or explicit like :dismissible="false" with a colon prefix.

::alert{type="warning" :dismissible="true"}
This is a dismissible warning alert. The dismissible prop uses a colon because it's a JavaScript expression.
::

Slots let you pass multiple content blocks to a component. Named slots use #slot-name syntax. Components can have a default slot for main content plus named slots for specific areas like headers, footers, or actions. This pattern keeps markdown readable while supporting complex component structures.

::card
#title
Component Title

#default
This is the main content that goes in the default slot.

#footer
Footer content with [links](https://example.com) and **formatting**.
::

Built-in Docus Components

Lithos inherits Docus's component library, giving you professionally designed elements for common documentation patterns. The ::alert component displays highlighted messages in various colors. The ::badge component creates inline labels for versions, statuses, or categories. The ::code-group component displays multiple code examples in tabs, perfect for showing the same operation across different tools or languages.

Tabs organize related content into a compact interface. Use ::tabs with nested :::tabs-item components to create tabbed sections. This works well for showing different approaches to the same task, separating preview and code views, or organizing platform-specific instructions. Readers appreciate tabs because they reduce scrolling while keeping alternatives readily accessible.

Lists and steps components structure sequential information. The ::steps component displays numbered instructions with visual emphasis, making tutorials and setup guides easier to follow. Unlike plain ordered lists, steps have stronger visual weight and clearer progression indicators, helping readers track their progress through multi-step processes.

Custom Components and Extensions

You can create custom Vue components in the components/ directory and use them in markdown immediately. Lithos auto-imports global components, so components/FeatureComparison.vue becomes available as ::feature-comparison in markdown. This extensibility means you can build domain-specific documentation tools like API explorers, interactive calculators, or data visualizations without leaving the markdown writing experience.

Component props can accept complex data by passing JavaScript expressions with the colon prefix. Array props use :items="['one', 'two', 'three']" and object props use :config="{ key: 'value' }". This lets you pass configuration data from frontmatter or page-level constants into components, creating parameterized documentation that adapts based on context.

Lithos includes internal components like ObsidianCallout, ObsidianBase, and NoteEmbed that render Obsidian syntax. You never invoke these manually -- write > [!tip] and Lithos transforms it to a callout component automatically. Write ![[Note]] and it becomes an embed. Write a ```base code block and it renders as a structured data view. The transform happens at build time, so you see the same syntax in Obsidian and on your published site.

Frontmatter Best Practices

Frontmatter is YAML metadata at the top of markdown files, enclosed in triple-dash fences. It controls how Lithos displays, organizes, and indexes your content. Well-crafted frontmatter improves SEO, navigation, and reader experience.

Essential Frontmatter Fields

The title field overrides the filename as the page's display title. Use proper capitalization and spacing—"Getting Started" instead of "getting-started"—because this appears in navigation, page headers, and search results. Keep titles concise but descriptive, typically 3-7 words. Longer titles get truncated in narrow viewports, while shorter titles may lack context.

The description field provides a one-sentence summary of the page content. This appears in search engine results, link previews, and social media cards, making it crucial for SEO. Aim for 120-160 characters—enough to convey the page's purpose without being truncated. Good descriptions answer "what will I learn from this page?" and include relevant keywords naturally.

The icon field sets a visual identifier using Lucide icons in the format i-lucide-icon-name. Icons appear in the navigation sidebar, helping readers scan the menu visually. Choose icons that match your content's purpose—use i-lucide-rocket for getting started, i-lucide-settings for configuration, i-lucide-book-open for guides. Consistent icon usage creates visual patterns that aid navigation.

Navigation Control

The order field controls page position within its parent folder. Lower numbers appear first, so order: 1 puts a page at the top of the section while order: 99 sinks it to the bottom. Use spacing like 10, 20, 30 instead of 1, 2, 3 to leave room for insertions without renumbering everything. Pages without an order field sort alphabetically after ordered pages.

The navigation object provides navigation-specific overrides. Set navigation.title to use different text in the sidebar than the page header. Use navigation.icon to override the icon specifically for sidebar display. Set navigation: false to hide a page from the sidebar entirely while keeping it accessible via direct URL or wikilinks—useful for landing pages or special routes.

The tags field accepts an array of strings for categorization. Tags enable filtering, searching, and dynamic content queries. Use lowercase, hyphen-separated tags like [getting-started, installation, beginner] for consistency. Tags power the Structured Data system, letting you create dynamic lists of related pages or topical indexes.

SEO and Social Media

The head object adds custom HTML head elements for advanced SEO control. Define head.meta as an array of meta tag objects to set keywords, author, or custom properties. Define head.link to add canonical URLs or alternate language versions. These fields override defaults from app.config.ts for individual pages.

Open Graph tags control how pages appear when shared on social media. Set og:image to specify a preview image, og:type to define content type (article, website, etc.), and og:description to override the standard description for social contexts. Twitter Card tags (twitter:card, twitter:image) work similarly for Twitter-specific previews.

The published field (true/false) controls whether a page appears in the public site. Set published: false to keep drafts in your vault without exposing them to readers. This is cleaner than using folder ignore patterns because you control visibility per-file and can easily toggle pages between draft and published states by changing a single field.

Images and Assets Handling

Lithos treats images and assets as first-class content. Store images alongside markdown files in your vault, and Lithos handles path resolution and optimization automatically.

Image Placement and References

Place images in the same folder as the markdown file that references them, or create a dedicated assets/ or images/ subfolder within your vault. Reference images using Obsidian syntax ![[image.png]] or standard markdown syntax ![alt text](image.png). Both work, but Obsidian syntax is more forgiving about paths—Lithos resolves the image regardless of its location in the vault.

Alt text describes images for screen readers and displays when images fail to load. Write descriptive alt text that conveys the image's purpose and content. For screenshots, describe what the screenshot shows: "Navigation sidebar showing collapsed sections" rather than just "screenshot." For diagrams, summarize the diagram's message: "Architecture diagram showing three-tier system design." Skip alt text only for purely decorative images.

Image sizing and alignment use standard HTML attributes or MDC syntax. The markdown format ![alt](image.png){width=500} sets explicit dimensions. For responsive images that scale with the viewport, use CSS classes like {class="w-full md:w-2/3"} which apply Tailwind utilities. Most images work best at full content width on mobile with constrained width on desktop.

Asset Organization Strategies

Small vaults can keep images alongside markdown without organization overhead. As your vault grows, create a consistent folder structure. Options include a global assets/ folder at vault root, per-section images/ folders (like guide/images/), or colocated assets where tutorial.md has a companion tutorial-assets/ folder.

Lithos processes images through Nuxt's asset pipeline, which provides automatic optimization for production builds. Images are compressed, converted to modern formats like WebP where supported, and cached with content hashing for efficient CDN delivery. You don't need to manually optimize images—Lithos handles this during nuxt generate.

External images using full URLs ![alt](https://example.com/image.png) work but bypass optimization and require external availability. Use external images for content you don't control (user avatars, external logos) but prefer local images for content you manage. Local images are guaranteed to work and benefit from optimization and versioning alongside your content.

Code Blocks and Syntax Highlighting

Code blocks display source code with syntax highlighting, line numbers, and copy functionality. Lithos uses Shiki for highlighting, which produces beautiful, accurate colors for dozens of programming languages.

Basic Code Block Syntax

Fence code blocks with triple backticks and specify the language for syntax highlighting. Common languages include javascript, typescript, python, bash, yaml, json, and markdown. The language identifier is case-insensitive and supports common aliases like js for JavaScript and ts for TypeScript.

\`\`\`javascript
function greet(name) {
  return `Hello, ${name}!`;
}
\`\`\`

Line numbers appear automatically for blocks longer than a few lines. Readers can copy code with a single click using the copy button that appears on hover. The copy functionality excludes line numbers and prompt characters, giving readers clean code ready to paste into their projects.

Inline code uses single backticks for short snippets within prose. Use inline code for variable names, function names, file paths, commands, and small code fragments. Don't use inline code for emphasis—that's what italics and bold are for. Overuse of inline code creates visual noise and reduces its effectiveness at indicating code vs. prose.

Advanced Code Features

Code groups display multiple related code blocks in a tabbed interface. This is perfect for showing the same operation in different languages, comparing before/after code, or presenting multiple solution approaches. Wrap multiple code blocks in a ::code-group component, using the bracket notation to label each tab.

::code-group
  \`\`\`javascript [JavaScript]
  console.log('Hello');
  \`\`\`

  \`\`\`python [Python]
  print('Hello')
  \`\`\`
::

Line highlighting emphasizes specific lines within a code block. Add {1,3-5} after the language identifier to highlight lines 1, 3, 4, and 5. This draws attention to key lines in longer examples, helping readers focus on what matters. Use highlighting sparingly—highlighting too much defeats the purpose of emphasis.

Diffs show code changes using the diff language identifier with plus and minus prefixes. Lines starting with + appear in green (additions) while lines starting with - appear in red (deletions). This is invaluable for migration guides, API changes, or tutorials showing incremental code development. Combine with language-specific highlighting using the format diff-javascript for colored diffs.