Project Structure

This guide provides a comprehensive overview of CodeInk’s file structure and explains the purpose of each directory and key file.

Repository Root

codeink/
├── src/                    # Source code
├── public/                 # Static assets
├── astro.config.mjs        # Astro configuration
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── wrangler.toml           # Cloudflare deployment config
├── bun.lock               # Dependency lock file
├── README.md              # Project documentation
└── LICENSE                # MIT License

Source Directory (`src/`)

The src/ directory contains all application code:

src/
├── components/            # Reusable Astro components
├── layouts/               # Page layouts
├── pages/                 # Route pages (file-based routing)
├── scripts/               # Client-side TypeScript
├── lib/                   # Utility libraries and helpers
├── styles/                # Global CSS and themes
└── assets/                # SVG icons and images

Components (`src/components/`)

Reusable UI components built with Astro:

Editor.astro

The main editor component containing:

CodeMirror editor pane
Preview pane
Resize handle between panes
Loading overlay
View mode management (editor/split/preview)

Location: src/components/Editor.astroKey Features:

Responsive layout with mobile support
Sticky pane headers
Custom resize handle with hover effects

Header.astro

Top navigation bar with:

Logo and site title
View mode tabs (optional)
Theme toggle
Export button

Location: src/components/Header.astro

StatusBar.astro

Bottom status bar displaying:

Save status (idle/saving/saved)
Markdown lint issues count
Auto-fix button

Location: src/components/StatusBar.astro

ViewTabs.astro

Toggle buttons for view modes:

Editor only
Split view (default)
Preview only

Location: src/components/ViewTabs.astro

ThemeToggle.astro

Button to switch between light and dark themes.Location: src/components/ThemeToggle.astro

CodeBlock.astro

Syntax-highlighted code block component used in content pages.Location: src/components/CodeBlock.astro

Card.astro & Button.astro

Reusable UI primitives for marketing/content pages.Locations:

src/components/Card.astro
src/components/Button.astro

Layouts (`src/layouts/`)

Page layout templates:

Layout.astro
ContentLayout.astro

Base layout for all pages.Location: src/layouts/Layout.astroIncludes:

HTML document structure
Meta tags (SEO, Open Graph, Twitter)
Theme initialization script
Global styles import
Structured data (JSON-LD)

Usage:

---
import Layout from "@/layouts/Layout.astro"
---
<Layout title="Page Title" description="Page description">
  <!-- Page content -->
</Layout>

Content page layout for documentation and guides.Location: src/layouts/ContentLayout.astroFeatures:

Responsive content wrapper
Typography styles
Header and footer

Pages (`src/pages/`)

File-based routing - each .astro file becomes a route:

File	Route	Purpose
`index.astro`	`/`	Landing page
`editor.astro`	`/editor`	Main editor interface
`documents.astro`	`/documents`	Document management page
`about.astro`	`/about`	About page
`markdown-cheat-sheet.astro`	`/markdown-cheat-sheet`	Markdown syntax guide
`katex-math-guide.astro`	`/katex-math-guide`	KaTeX math reference
`mermaid-diagrams-guide.astro`	`/mermaid-diagrams-guide`	Mermaid diagram examples
`404.astro`	`/404`	Error page
`robots.txt.ts`	`/robots.txt`	SEO robots file
`llms.txt.ts`	`/llms.txt`	AI/LLM documentation

Scripts (`src/scripts/`)

Client-side TypeScript modules:

Core Editor
CodeMirror Setup
Preview System
Markdown Linting
Other Scripts

editor.ts

Main editor initialization and orchestrationLocation: src/scripts/editor.tsResponsibilities:

Initialize CodeMirror editor
Load/create documents from URL hash
Set up auto-save (1 second debounce)
Connect editor to preview
Manage status bar state
Handle theme changes

Key Functions:

export function initEditor(): void

codemirror-setup.ts

CodeMirror editor configurationLocation: src/scripts/codemirror-setup.tsExports:

createEditor(parent: HTMLElement, initialDoc: string): EditorView
destroyEditor(): void
setEditorTheme(theme: "light" | "dark"): void
getEditorContent(): string
setEditorContent(content: string): void

Extensions:

basicSetup - line numbers, search, etc.
markdown - Markdown language mode
linter - Real-time markdown linting
Theme compartment for dynamic switching

preview.ts

Markdown preview renderingLocation: src/scripts/preview.tsExports:

initPreview(target: HTMLElement): () => void
renderPreview(content: string, target: HTMLElement): Promise<void>

Process:

Listen for editor-change events
Debounce (300ms)
Render markdown to HTML
Initialize Mermaid diagrams
Attach copy buttons to code blocks

markdown-linter.ts

Real-time markdown linting and auto-fixLocation: src/scripts/markdown-linter.tsExports:

markdownLint(view: EditorView): Diagnostic[]
fixMarkdown(text: string): string

Linting Rules:

Uses remark-preset-lint-recommended
Custom heading fix plugin
Undefined reference checking

Libraries (`src/lib/`)

Shared utility code:

db.ts

IndexedDB wrapper for document storageExports:

getAllDocs(): Promise<Document[]>
getDoc(id: string): Promise<Document | null>
saveDoc(doc: Document): Promise<void>
deleteDoc(id: string): Promise<void>

Location: src/lib/db.ts

markdown.ts

Markdown processing pipelineExports:

renderMarkdown(content: string): Promise<string>
extractTitle(content: string): string

Features:

Marked parser with extensions
Shiki syntax highlighting
Custom code block renderer
Mermaid diagram support

Location: src/lib/markdown.ts

markdown-title.ts

Extract document title from markdownExtracts first heading (H1-H6) or falls back to “Untitled”Location: src/lib/markdown-title.ts

default-markdown.md

Default document content for new documentsImported as raw string: import DEFAULT_MARKDOWN from "@/lib/default-markdown.md?raw"Location: src/lib/default-markdown.md

Shiki Highlighter (`src/lib/shiki/`)

highlight.ts
transformers.ts

Syntax highlighting engineLocation: src/lib/shiki/highlight.tsFeatures:

On-demand language loading
60+ supported languages
Light and dark themes
Language aliases (js → javascript, etc.)

Main Export:

highlightCode(code: string, lang?: string): Promise<string>

Shiki transformers for custom renderingLocation: src/lib/shiki/transformers.tsTransformers:

showLineNumbers() - Add line numbers
wordWrapContent() - Enable word wrapping
addLanguageProperty() - Add language data attribute

Styles (`src/styles/`)

Global CSS organized by concern:

global.css

Main stylesheet importing all other CSS filesLocation: src/styles/global.css

tokens.css

CSS custom properties (design tokens):

Colors (background, foreground, primary, etc.)
Typography (font families, sizes)
Spacing and sizing
Border radius

Location: src/styles/tokens.css

base.css

Base element styles and resetsLocation: src/styles/base.css

prose.css

Typography styles for markdown previewApplied via .markdown-prose classLocation: src/styles/prose.css

code.css

Code block and syntax highlighting stylesLocation: src/styles/code.css

utilities.css

Custom utility classesLocation: src/styles/utilities.css

integrations.css

Styles for third-party integrations (Mermaid, KaTeX)Location: src/styles/integrations.css

Assets (`src/assets/`)

Static SVG icons and images:

src/assets/
├── logo.svg                    # CodeInk logo
├── icons/
│   ├── tech/                   # Technology logos
│   │   ├── astro.svg
│   │   ├── bun.svg
│   │   ├── mermaid.svg
│   │   ├── tailwind.svg
│   │   └── ts.svg
│   └── toggle-theme.svg        # Theme toggle icon

Public Directory (`public/`)

Static files served as-is:

public/
├── favicon.svg                 # Site favicon
├── favicon-192.png             # PWA icon (192x192)
├── favicon-512.png             # PWA icon (512x512)
├── apple-touch-icon.png        # iOS home screen icon
├── og-image.png                # Social media preview image
└── icons/
    └── lang/                   # Code language icons
        ├── default.svg
        ├── javascript.svg
        ├── python.svg
        ├── typescript.svg
        └── ... (60+ language icons)

Configuration Files

astro.config.mjs
package.json
tsconfig.json
wrangler.toml

Astro framework configurationLocation: astro.config.mjsKey Settings:

{
  site: 'https://codeink.app',
  output: 'server',
  adapter: cloudflare(),
  integrations: [sitemap()],
  vite: {
    plugins: [tailwindcss()],
    build: {
      rollupOptions: {
        output: {
          manualChunks() { /* ... */ }
        }
      }
    }
  }
}

Node.js package configurationLocation: package.jsonScripts:

dev - Start development server
lint - Run type checking
build - Production build
preview - Preview production build

Key Dependencies:

astro - Framework
codemirror - Editor
marked - Markdown parser
shiki - Syntax highlighter
mermaid - Diagrams
katex - Math rendering

TypeScript configurationLocation: tsconfig.jsonSettings:

Path alias @/* → src/*
Strict type checking enabled
ES2022 target

Cloudflare Pages deployment configLocation: wrangler.toml

name = "codeink"
compatibility_date = "2024-01-01"
pages_build_output_dir = "dist"

Import Aliases

CodeInk uses the @/ alias for cleaner imports:

// Instead of:
import { saveDoc } from "../../../lib/db"

// Use:
import { saveDoc } from "@/lib/db"

Alias mapping (tsconfig.json):

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

File Naming Conventions

Components

PascalCase with .astro extensionExamples: Editor.astro, StatusBar.astro

Scripts

kebab-case with .ts extensionExamples: editor.ts, markdown-linter.ts

Styles

kebab-case with .css extensionExamples: global.css, code.css

Pages

kebab-case with .astro extensionExamples: index.astro, markdown-cheat-sheet.astro

Key File Relationships

Understanding how files connect:

Finding Code

By Feature
By Type
By Layer

Feature	Primary Files
Editor	`components/Editor.astro`, `scripts/editor.ts`, `scripts/codemirror-setup.ts`
Preview	`scripts/preview.ts`, `lib/markdown.ts`
Storage	`lib/db.ts`, `scripts/editor.ts`
Linting	`scripts/markdown-linter.ts`
Highlighting	`lib/shiki/highlight.ts`
Themes	`layouts/Layout.astro`, `styles/tokens.css`

Type	Location	Pattern
UI Components	`src/components/`	`*.astro`
Pages/Routes	`src/pages/`	`*.astro`
Client Scripts	`src/scripts/`	`*.ts`
Utilities	`src/lib/`	`*.ts`
Styles	`src/styles/`	`*.css`
Icons	`src/assets/icons/`	`*.svg`

Layer	Files
Presentation	`components/.astro`, `layouts/.astro`
Logic	`scripts/.ts`, `lib/.ts`
Styling	`styles/*.css`
Data	`lib/db.ts`

Next Steps

Setup

Set up your development environment

Architecture

Understand the technical architecture

Contributing

Start contributing to CodeInk

Getting Started

Contributing

​Repository Root

​Source Directory (src/)

​Components (src/components/)

​Layouts (src/layouts/)

​Pages (src/pages/)

​Scripts (src/scripts/)

​editor.ts

​codemirror-setup.ts

​preview.ts

​markdown-linter.ts

​mermaid-renderer.ts

​view-mode.ts

​resize-handle.ts

​status-bar.ts

​export.ts

​documents.ts

​copy-handler.ts

​logo-loop.ts

​landing-nav-cta.ts

​Libraries (src/lib/)

db.ts

markdown.ts

markdown-title.ts

default-markdown.md

​Shiki Highlighter (src/lib/shiki/)

​Styles (src/styles/)

global.css

tokens.css

base.css

prose.css

code.css

utilities.css

integrations.css

​Assets (src/assets/)

​Public Directory (public/)

​Configuration Files

​Import Aliases

​File Naming Conventions

Components

Scripts

Styles

Pages

​Key File Relationships

​Finding Code

​Next Steps

Setup

Architecture

Contributing

Build docs developers (and LLMs) love

Repository Root

Source Directory (`src/`)

Components (`src/components/`)

Layouts (`src/layouts/`)

Pages (`src/pages/`)

Scripts (`src/scripts/`)

editor.ts

codemirror-setup.ts

preview.ts

markdown-linter.ts

mermaid-renderer.ts

view-mode.ts

resize-handle.ts

status-bar.ts

export.ts

documents.ts

copy-handler.ts

logo-loop.ts

landing-nav-cta.ts

Libraries (`src/lib/`)

Shiki Highlighter (`src/lib/shiki/`)

Styles (`src/styles/`)

Assets (`src/assets/`)

Public Directory (`public/`)

Configuration Files

Import Aliases

File Naming Conventions

Key File Relationships

Finding Code

Next Steps