md-web

# MD Web - Markdown to Web Page Upload raw `.md` files to an S3-compatible storage bucket, where a pre-deployed Docsify server automatically renders them as web pages. This avoids sending long text in the conversation. ## When to use this skill **Uploaded content is publicly accessible.** Only use this skill when the user explicitly requests it: - User wants to **show or preview content as a web page** in a browser - User wants to **generate, export, or publish** content as a web page - User wants a **shareable link** to content - User wants output **delivered as a web page** rather than as long text in chat - User wants to **compile or organize content and present it as a web page** - User invokes this skill by name (e.g., `/md-web`) ## How to use this skill ### Step 1: Check configuration Check if `~/.md-web/config.json` exists (cross-platform: use the user's home directory). If it does NOT exist or has empty fields, follow the **Configuration** section below first. ### Step 2: Prepare the markdown file Either use an existing `.md` file, or write the content to a temporary file. Choose the temp path based on the current platform (e.g., `/tmp/` on Linux/macOS, system temp dir on Windows). Use whichever path works in the current shell environment. ### Step 3: Upload via upload.js ```bash node {SKILL_DIR}/upload.js <local-file> <remote-key> ``` - `{SKILL_DIR}`: the base directory of this skill (shown at the top when skill is loaded) - `<remote-key>`: a descriptive lowercase name with hyphens (e.g., `api-docs.md`, `project-guide.md`). A timestamp is prepended automatically to avoid filename collisions. - On first run, the script auto-detects and deploys Docsify server files. No manual setup needed. ### Step 4: Return the result - **On success**: the script prints the URL. Reply with only the filename and clickable link. Do NOT paste the markdown content into the chat. - **On failure** (non-zero exit code): report the error to the user, then fall back to sending the markdown content as text directly in the chat. Example success output: > `api-docs` - https://example.r2.dev/index.html#/20260305-091500-api-docs ## Configuration This only needs to happen once. On subsequent runs, `config.json` already exists. 1. Tell the user this skill needs an S3-compatible storage bucket with public access. Point them to `{SKILL_DIR}/README.md` for detailed setup instructions (Cloudflare R2 / AWS S3 / other S3-compatible services). 2. Ask the user to provide these 5 required fields: - **access_key**: API access key ID - **secret_key**: API secret access key - **endpoint**: S3 endpoint hostname, without `https://` (e.g., `ACCOUNT_ID.r2.cloudflarestorage.com`) - **bucket**: bucket name - **public_url**: public access URL. If the user has a custom domain bound to the bucket, use that (e.g., `https://docs.example.com`); otherwise use the default R2.dev URL (e.g., `https://pub-XXXX.r2.dev`). **Recommend custom domain** for production use — R2.dev URLs have rate limits. 3. Ask about optional settings: - **region**: S3 region. Use `auto` for Cloudflare R2, or the actual region for AWS S3 (e.g., `us-east-1`). Default is `auto`. - **expire_days**: how many days before uploaded markdown files are automatically deleted from the bucket. Default is `30`. Set to `0` to keep files forever. The script sets an S3 lifecycle rule automatically — only timestamped uploads are affected; Docsify server files are never expired. **Note**: this requires the API token to have **Admin Read & Write** permission (not just Object Read & Write). If the token lacks permission, the script will warn but still upload normally — the user can set the lifecycle rule manually in the Cloudflare Dashboard instead. 4. Write the config to `~/.md-web/config.json` (create the `~/.md-web/` directory if it doesn't exist). Use the user's home directory (`$HOME` on Unix, `%USERPROFILE%` on Windows): ```json { "access_key": "...", "secret_key": "...", "endpoint": "...", "bucket": "...", "region": "auto", "public_url": "...", "expire_days": 30 } ``` 5. Then proceed with the upload. ## Important notes - Do NOT generate HTML. Just upload the raw `.md` file — Docsify handles rendering. - Do NOT send markdown content to the chat unless upload fails. - `upload.js` uses only Node.js built-in modules (zero dependencies). - All Docsify assets (JS/CSS) are bundled locally — no external CDN dependency at runtime. ## External endpoints This skill connects only to the S3 endpoint configured by the user in `config.json`. No data is sent to the skill author or any third-party service. | Endpoint | Purpose | Data sent | |----------|---------|-----------| | User's S3 endpoint (`config.json → endpoint`) | Upload .md files and Docsify server assets | File content, S3 auth headers | ## Security & privacy - All uploaded content is **publicly accessible** via the generated URL. - Credentials (`access_key`, `secret_key`) are stored locally in `~/.md-web/config.json` (outside the skill directory, safe from upgrades) and only sent to the user's own S3 endpoint for authentication. - No telemetry, analytics, or data collection by the skill itself. - `upload.js` uses only Node.js built-in modules — no third-party dependencies. By using this skill, markdown content is uploaded to **your own** S3-compatible storage bucket and made publicly accessible. No data is sent to the skill author or any third-party service. Only install if you trust the storage provider you configure.