Davia Documentation

Davia documentation is designed to be ultra-visual, concise, and educational. Follow these principles to ensure high-quality documentation:

Visual Requirements

• Visuals over Prose: Use visuals to do the teaching. Text should be extremely concise (short sentences, bullet points) rather than long paragraphs.
• Mandatory Visuals: Every HTML page must have at least one visual element.
  • Excalidraw Whiteboards: Use these for explaining flows, architecture, backend requests, frontend journeys, deployments, or schemas. Default to a whiteboard if a visual is requested.
  • Database Views: Use these for structured information like API endpoints, configuration tables, process lists, or feature lists. Use these instead of long prose lists or tables.

Structural Principles

• One Concept Per Page: Do not mix multiple concepts on a single page. If you introduce a new concept, create a new HTML page.
• Hierarchical Organization: Use the .davia folder structure to create a hierarchy.
  • High-level overview pages should live at the root of the .davia documentation tree.
  • Detailed or implementation-specific pages should be placed in subfolders (e.g., architecture/frontend.html) as children of relevant overview pages.
• Scannability: Use HTML elements like code blocks, separators, and lists strategically. Use bold and italic formatting to highlight key ideas, steps, or warnings. Use emojis to make content engaging.

Davia manages three primary types of content within a workspace. Understanding these is critical for instructing the agent or structuring your project:

1. HTML Pages (*.html): The main user-facing content. These follow strict Tiptap schema guidelines and are used for text, formatting, and embedding interactive elements.
2. MDX Components (components/*.mdx): Reusable interactive components. These contain only shadcn components, JSX expressions, and custom components—no regular markdown content is allowed here. They are embedded in HTML via <mdx-component data-path="..."></mdx-component>.
3. Data Files (data/*.json): Shared structured data used for configurations, metadata, or datasets. These can be used by components or embedded in HTML via <database-view data-path="..."></database-view>.

File Path Conventions:

• HTML: page1/page2/page3.html
• MDX: components/name.mdx
• Data: data/name.json

Davia documentation is built using three distinct content types stored within the .davia/assets folder at the repository root. Understanding the relationship between these types is critical for creating functional documentation.

1. HTML Pages

• Purpose: The primary user-facing content (text, headings, lists, blockquotes).
• Extension: .html
• Requirement: Every page must contain at least one visual element (either an Excalidraw whiteboard or a Database View).
• Naming Convention: The file path must be the kebab-case version of the page's top-level <h1> title. For example, <h1>Plant Tracker</h1> must be saved as plant-tracker.html.
• Embedding: You embed other content types into HTML pages using specific tags:
  • MDX: <mdx-component data-path="components/path.mdx"></mdx-component>
  • Data View: <database-view data-path="data/path.json"></database-view>
  • Excalidraw: <excalidraw data-path="data/diagram.json"></excalidraw>

2. MDX Components

• Purpose: Reusable, interactive functional components (using React/shadcn).
• Extension: .mdx
• Location: The components/ directory.
• Constraint: MDX files should contain no regular markdown content; they are purely for functional components, JSX expressions, and shadcn components.

3. Data Files

• Purpose: Shared structured data (configs, metadata, datasets).
• Extension: .json
• Location: The data/ directory.
• Usage: Used by MDX components for state/data binding or embedded directly into HTML via <database-view>.

When creating documentation that includes interactive features, you must follow a strict, progressive, page-by-page creation order to prevent errors caused by missing dependencies. Never create an HTML page before its required components or data files exist.

The Progressive Page-by-Page Approach

For every new page you intend to create, follow these steps in exact order:

1. Create Data Files: Create any required .json files in the data/ directory first.
2. Create MDX Components: Create the .mdx component file(s) in the components/ directory.
   • Build the interactive functionality using React/shadcn.
   • Bind data using the useData hook: const { data, updateData } = useData(dataset); (e.g., import dataset from "~/data/dataset.json").
3. Create the HTML Page: Only after the data and components are ready, create the .html file.
   • Embed the component using <mdx-component data-path="components/name.mdx"></mdx-component>.

Repeat this entire cycle for each subsequent page. Do not attempt to create all components for all pages at once; work one page at a time to ensure all dependencies are satisfied before the HTML is rendered.

When requesting new interactive features or pages, the Davia agent follows a strict, progressive, page-by-page workflow. To avoid errors, components and data must exist before the HTML page that references them is created.

Mandatory Workflow per Page:

1. Create Data Files FIRST: Place required .json files in the data/ directory.
2. Create MDX Components SECOND: Create the .mdx files in the components/ directory. Use React/shadcn components and bind data using const { data, updateData } = useData(dataset).
3. Create HTML Page LAST: Only after the data and components exist, create the .html file and embed the component using the <mdx-component> tag.

Critical Rules:

• Never create an HTML file before its required components.
• Do not create all components for all pages first; work page-by-page (complete all steps for Page 1, then move to Page 2).

The @davia/web application uses a flat configuration format via eslint/config. It integrates eslint-config-next/core-web-vitals and eslint-config-next/typescript to enforce Next.js best practices and TypeScript rules. You can customize the global ignore patterns using the globalIgnores function to override the default Next.js ignores (which typically include .next/**, out/**, build/**, and next-env.d.ts).

import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTs from "eslint-config-next/typescript";

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    ".next/**",
    "out/**",
    "build/**",
    "next-env.d.ts",
  ]),
]);

export default eslintConfig;