vitya
43f9912c54
Build was RED: 5 skills in skills/ were unmapped (meta-host-routing,
ralph-loop-execution, setup-agents-task-runner, task-format,
using-system-snapshot) — "unmapped entries" abort. Mapped all 5 as `pending`
(conservative placeholder, no auto-commitment; each keeps its own mode decision).
meta-host-routing mapping executes task meta-host-routing-hermes-mapping.
- inter-session-peer-discipline: pending -> auto (category meta). Gate
("non-implementer test-trigger + review") satisfied — both VERDICT PASS this
session; purely behavioral, no tool-side effects, no Windows-PS hook. Human-ratified.
- session-inbox-monitor: reason updated — behavioral gate CLEARED (test-trigger +
review PASS), STAYS pending on two independent tool-side blockers (Linux port of
the PS hook + settings.json/process-kill audit), not on behavioral verification.
- dist-hermes regenerated: build now GREEN (auto 14 / manual 2 / skip 9 / pending 13);
materialized dist-hermes/meta/inter-session-peer-discipline/; synced stale
using-markitdown / using-tasks copies (source had been bumped without a hermes rebuild).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
79 lines
5.4 KiB
Markdown
79 lines
5.4 KiB
Markdown
---
|
|
name: using-markitdown
|
|
version: 1.0.1
|
|
description: Use when capturing external content into a markdown-based knowledge base, wiki `raw/` directory, or any pipeline that must preserve the source's full text — for web pages, PDFs, DOCX/PPTX/XLSX, EPUB, CSV/JSON/XML, ZIP archives, images (with OCR/EXIF), audio (with transcription), or YouTube URLs. Also use when WebFetch returned an LLM-summarized version but the raw content is what's needed.
|
|
---
|
|
|
|
# using-markitdown
|
|
|
|
> Convert almost any path or URL to plain markdown using Microsoft's `markitdown` CLI (v0.1.6, on `PATH`). Returns **raw textual content**, not an LLM summary.
|
|
|
|
## Tool
|
|
|
|
```
|
|
markitdown <path|url> # → markdown to stdout
|
|
markitdown <path|url> -o out.md # → write markdown to a file
|
|
cat file.pdf | markitdown # → read from stdin (use -x/-m to hint the format)
|
|
```
|
|
|
|
The positional argument accepts a **local file path** (host path, normal slashes) or an `http://` / `https://` URL. The CLI runs natively, so it sees your full host filesystem — no Docker mount, no `file://` URI translation, no path rewriting.
|
|
|
|
Useful flags: `-o <file>` (write to a file instead of stdout), `-x <ext>` / `-m <mime>` (format hint when reading from stdin).
|
|
|
|
## Local files
|
|
|
|
Pass the host path directly — relative or absolute, with native separators:
|
|
|
|
```
|
|
markitdown C:\Users\vitya\modular\heart-and-mask\.wiki\raw\foo.html -o foo.md
|
|
```
|
|
|
|
No mount caveats: the CLI is a normal local process. The old Docker `-v` mount translation and `/c:/Users/...` `[Errno 2]` symptom no longer apply.
|
|
|
|
**Filenames.** Non-ASCII filenames (Cyrillic, etc.) still travel better as Latin kebab-case through downstream wiki/ingest steps. Rename to Latin kebab-case before saving the output, per `.wiki/CLAUDE.md` naming rules.
|
|
|
|
## When to use
|
|
|
|
- Filling a wiki's `raw/` directory from a URL or local PDF/DOCX.
|
|
- Datasheets, papers, blog posts, GitHub READMEs, Obsidian Web Clipper outputs, KiCad netlist exports — anything where the source text matters and lossy summarization would break later ingest steps.
|
|
- Any time the next step is "save the source verbatim before summarizing".
|
|
|
|
## When NOT to use
|
|
|
|
- You only need a *summary* or an *answer about* a page → use **WebFetch** (cheaper, runs through a small model, returns prose).
|
|
- The URI is GitHub/PR/issue/release content → use `gh` CLI (richer metadata, structured output).
|
|
- The URI is private/authenticated (GDocs, Confluence, Jira, Slack, Notion, `share.google/*` sign-in walls) → markitdown receives the **public-facing fallback page** (sign-in screen, cookie banner) and returns *that* as markdown. Verify the result is real content before saving.
|
|
- **The URI is a browser-rendered web page the user is already viewing** → ask the user to capture it via **Obsidian Web Clipper** (browser extension, runs Readability extraction client-side) and drop the resulting `.md` into `raw/`. Web Clipper output is dramatically cleaner than markitdown's HTML pass — no nav chrome, no sidebar history, no cookie banners — plus it carries YAML frontmatter (title / source URL / date) out of the box. Reserves markitdown for things browsers can't easily save (PDF, DOCX, PPTX, XLSX, EPUB, local files). Note: rename the resulting file to Latin kebab-case before ingest (Web Clipper preserves the page `<title>` verbatim, often non-ASCII).
|
|
|
|
## Pattern: ingest a remote source into a wiki
|
|
|
|
```
|
|
1. markitdown "https://example.com/foo.pdf" -o .wiki/raw/<slug>.md (kebab-case, Latin only)
|
|
2. Inspect the head of the result. If it looks like a sign-in/cookie/consent page, abort — ask the user for an alternative (manual save, paste, authenticated source).
|
|
3. Register the new file in .wiki/raw/README.md.
|
|
4. Hand off to the wiki ingest workflow (creates sources/<slug>.md summary + entity/concept updates).
|
|
```
|
|
|
|
For a huge (book-length) document, write straight to a file with `-o` and summarize *from the saved file* — do not pipe the whole markdown through working context.
|
|
|
|
## Common gotchas
|
|
|
|
| Symptom | Cause | Fix |
|
|
|---|---|---|
|
|
| Output is a Google/Microsoft sign-in page in some random language | URI behind auth wall | Ask user to export the content manually (Save as PDF, copy-paste) and put it in `raw/` |
|
|
| Output is mostly nav/cookie banner text | Site is JS-rendered or anti-bot | Try the cached or print URL; or ask user for HTML export |
|
|
| Output lacks images / diagrams | Markdown is text-only by design | Save the original asset separately under `raw/assets/`; reference it from the `sources/` summary |
|
|
| `markitdown: command not found` | CLI not on `PATH` | Confirm with `markitdown --version` (expect `markitdown 0.1.6`); install with `pip install markitdown[all]` if missing |
|
|
| Huge output (book-length) | Whole document converted in one call | Use `-o <file>` to save raw, then summarize *from the saved file* — do not hold the entire markdown in working context |
|
|
|
|
## Quick contrast with WebFetch and Web Clipper
|
|
|
|
| | markitdown | WebFetch | Obsidian Web Clipper |
|
|
|---|---|---|---|
|
|
| Returns | raw markdown of the source | LLM answer about the source | Readability-extracted markdown with YAML frontmatter |
|
|
| Use for | PDF / DOCX / non-browser-friendly | one-shot Q&A | any browser-viewable web page |
|
|
| Auth-aware | no | no | **yes** (uses the user's logged-in browser session) |
|
|
| Chrome / nav stripped | partial (still verbose) | n/a (model picks signal) | **yes** (clean) |
|
|
| Handles PDFs / DOCX | yes | text-only HTML extraction | no (web pages only) |
|
|
| Who triggers it | Claude | Claude | the user (manual click) |
|