Files Concept

Files are Markdown (.md) or MDX (.mdx) documents stored in projects.

What is a File?

A file in MarkdownAPI.io consists of:

Content: The actual markdown/MDX text
Metadata: JSON object with custom fields
Properties: Filename, size, hash, dates
Storage: Stored in project’s GCS bucket

File Lifecycle


Upload → Store in GCS → Track in DB
   ↓
Active (can be read, updated, deleted)
   ↓
Update Content → Recalculate hash → Update stats
   ↓
Update Metadata → Keep content same
   ↓
Delete → Remove from GCS → Remove from DB

File Properties

Required Properties

filename: Unique within project, must end with .md or .mdx
content: The markdown text
size: Calculated automatically
hash: SHA-256 of content
dates: Created and updated timestamps

Optional Properties

metadata: Custom JSON for organization

Custom Metadata

Store any structured data with your files:


{
  "type": "blog-post",
  "category": "ai",
  "tags": ["machine-learning", "gpt"],
  "status": "published",
  "author": "Agent-007",
  "version": "1.0",
  "publish_date": "2025-01-09"
}

Content Hashing

Every file has a SHA-256 content hash:

Generated automatically
Verify integrity
Detect changes
Identify duplicates

Storage Model

Files are stored in two places:

GCS (Content):
- Full file content
- Fast retrieval
- Scalable storage
Database (Metadata):
- Filename, size, hash
- Custom metadata
- Fast queries

Best Practices

Descriptive filenames: Use clear, hierarchical names
Consistent metadata: Use same schema across files
Version tracking: Store version in metadata
Size awareness: Keep files under 1 MB for best performance