@yieldcraft/doc-viewer

A pi-web workspace plugin for browsing, searching, rendering, and editing Markdown documentation from a project docs/ directory.

Doc Viewer gives every pi-web workspace a documentation panel: a collapsible file tree on the left, rendered Markdown on the right, Mermaid diagrams, full-text search, copyable code blocks, and a remote-safe Markdown editor.

What it does

Area	Behavior
Plugin type	pi-web plugin only
pi-web plugin id	doc-viewer
Plugin module	pi-web-plugin.js
Source directory	Workspace docs/ folder
File types	.md, .mdx, .markdown
Main action	Open Documentation Viewer (mod+shift+d)

Requirements

• pi-web with the stable workspace files plugin API.
• ⚠️ This version depends on the new files.writeFile() and files.deleteFile() plugin APIs introduced in the PR currently under review: https://github.com/jmfederico/pi-web/pull/23
• Until that PR is merged and released, this version of doc-viewer only works against a pi-web build that includes those APIs. Older pi-web releases do not provide context.files.writeFile / context.files.deleteFile, so editing and inline deletion will fail.

Features

• Recursive docs browser — discovers Markdown files under docs/, including nested folders.
• Readable tree navigation — shows the docs/ root, folder/file/index icons, H1 titles when available, and index.md first in each folder.
• Collapsed nested folders — nested folders start collapsed; click a folder row to expand or collapse it.
• Normal mode and focus mode — normal mode lives inside the pi-web workspace panel; focus mode uses a CSS overlay with toolbar on top, tree on the left, and the viewer on the right.
• Full-text search — searches all discovered docs files, sorts title matches first, and highlights matching snippets.
• Markdown rendering — supports headings, emphasis, links, images, lists, blockquotes, tables, horizontal rules, inline code, and fenced code blocks.
• Mermaid diagrams — renders fenced mermaid code blocks in the document view.
• Code block tools — code blocks are scrollable, preserve newlines, and include a copy button.
• Copy file content — toolbar action copies the selected Markdown file's raw content to the clipboard.
• Markdown edit mode — edit the selected document, then save or cancel without modifying pi-web itself.
• Stable file saves — writes changes through pi-web's stable workspace files.writeFile() API, so saves happen in the active workspace environment on both local and federated machines.
• Inline delete for docs/tmp/ files — each Markdown file directly inside docs/tmp/ shows a trash icon on the right side of the tree row. Clicking it deletes the file from the workspace after confirmation.

Install

Use the package through pi-web's plugin/package workflow once it is available from npm:

npm install @yieldcraft/doc-viewer

For local development, link this package into the local pi-web plugin directory:

npm run dev:link

To remove the development link:

npm run dev:unlink

The package advertises its plugin metadata in package.json:

{
  "piWeb": {
    "plugins": [
      {
        "id": "doc-viewer",
        "module": "pi-web-plugin.js"
      }
    ]
  }
}

Use

1. Add Markdown files to your workspace docs/ directory.
2. Open a pi-web workspace that has this plugin installed.
3. Run Open Documentation Viewer or press mod+shift+d.
4. Select a file from the tree to render it.
5. Use the toolbar to search, refresh the tree, copy the full file path, edit the file, or toggle focus mode.

Recommended docs layout

docs/
├── index.md
├── architecture.md
├── api-reference.md
└── guides/
    ├── index.md
    └── first-task.md

index.md files are shown first within their folder. If a document starts with an H1 heading, that heading is used as the display title.

Focus mode

Focus mode is a layout mode, not browser fullscreen. It does not call the browser Fullscreen API, does not use requestFullscreen, and does not exit on Esc.

In focus mode:

• the toolbar is fixed at the top;
• the docs tree stays on the left;
• the viewer/editor fills the right side;
• the divider between the tree and content is draggable — drag it to resize the sidebar, and the chosen width is remembered across sessions (clamped between 180px and 60% of the panel);
• the default split is approximately 25% navigation and 75% content until you drag the divider.

Use the focus button again to return to normal mode. In normal mode the divider is hidden and the layout is not resizable.

Mermaid example

```mermaid
flowchart LR
  Docs[docs/] --> Tree[Doc Viewer tree]
  Tree --> Rendered[Rendered Markdown]
  Rendered --> Diagram[Mermaid diagram]
```

Development notes

Doc Viewer follows pi-web's dynamic panel pattern:

• render() is synchronous and returns the static shell sections: <section class="toolbar"> and <section class="viewer">.
• Async file-tree and file-content work is scheduled after the shell mounts via a single scheduleRender() helper that tracks and cancels pending requestAnimationFrame/setTimeout callbacks.
• DOM updates use querySelectorAllDeep and requestAnimationFrame.
• The implementation does not call requestRender() from render().
• Edit saves and inline deletes use pi-web's stable context.files.writeFile() and context.files.deleteFile() APIs (no shell commands).

Run a syntax/import smoke test:

node --eval "import('./pi-web-plugin.js').then(() => console.log('unexpected browser globals ok')).catch(e => { if (String(e.message).includes('window is not defined')) console.log('Parsed OK'); else { console.error(e); process.exit(1); } })"

Check npm package contents:

npm pack --dry-run

Public package contents

The npm package allowlist is intentionally small:

• pi-web-plugin.js
• README.md
• docs/*.md
• .pi-web/tasks.json

Temporary working material and ignored artifacts must stay out of the public package.

Documentation

• Docs home
• Documentation guide
• Architecture
• Implementation approach
• Mermaid support
• API reference
• Troubleshooting

License

MIT