Blank Files Website

Laravel application that powers blankfiles.com. Browse and download minimal valid blank files by type and category. File data and assets are served from the filearchitect/blank-files repository via a configurable CDN.

Requirements

• PHP 8.2+
• Composer
• Node.js 18+ (for Vite frontend build)

Installation

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

Set CDN_URL in .env (see Configuration). Then build the frontend and run the app:

npm install && npm run build
php artisan serve

Or use Laravel Herd with a .test domain.

Configuration

Project structure

Deployment

On push to main, GitHub Actions:

1. Builds the frontend (Vite) with npm ci and npm run build.
2. SCPs public/build/ to the Forge server.
3. Triggers a Laravel Forge deployment.
4. Runs php artisan optimize:clear on the server.

Required repository secrets:

• FORGE_SSH_HOST — SSH host for the server.
• FORGE_SSH_USER — SSH user (e.g. forge).
• SSH_PRIVATE_KEY — Private key for SCP/SSH.
• FORGE_SERVER_ID — Forge server ID.
• FORGE_SITE_ID — Forge site ID.
• FORGE_API_KEY — Forge deploy token.

See .github/workflows/deploy.yml.

For developers and bots

Base URL

Production: https://blankfiles.com. HTML and JSON are available; use Accept: application/json where applicable.

Web routes

API routes (prefix api/v1)

Machine-friendly notes

• The canonical file catalog schema is defined in the blank-files repo: files/files.json (key files, array of { type, url, category, package? }).
• Download URLs: use the API url field for direct CDN access, or GET /files/download/{category}/{type} for a same-origin download with a predictable filename.
• Conditional requests are supported on API responses and sitemap (ETag, Last-Modified).
• Rate limits: public IP-based limits and optional API-key limits (X-API-Key).
• API usage analytics are logged to storage/logs/api-usage-*.log (configurable channel).
• Compatibility policy: API policy.

Client snippets

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // unchanged
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

Compatibility policy

• URL versioning is stable under /api/v1/*.
• Breaking changes require a new major API path version.
• Deprecated endpoints are kept for at least 90 days before removal.
• New fields may be added; clients should ignore unknown fields.

Related

• filearchitect/blank-files — Source of truth for the file list and blank file assets.

MCP server (for agent marketplaces/registries)

This repository now includes a minimal MCP server that exposes Blank Files as tool calls.

• Script: scripts/mcp/blankfiles-mcp.mjs
• Run: npm run mcp:server
• Optional env: BLANKFILES_BASE_URL (default: https://blankfiles.com)

Available MCP tools:

• list_blank_files — list files, optional filters (category, type, limit)
• files_by_type — list entries by extension
• file_by_category_type — deterministic single lookup by category + extension

Example local MCP client config entry:

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

Registry submission helpers:

• Template metadata: scripts/mcp/registry/server.json.template
• Publish checklist: scripts/mcp/registry/PUBLISHING.md

Published package workspace:

• packages/blankfiles-mcp (publish as @filearchitect/blankfiles-mcp)

License

This project is licensed under the MIT License.