Flow Documentation Framework

Embeddable documentation viewer for SKILL.md files. Single JS file, no server required for static mode. Includes server adapters for dynamic folder reading.

CDN

<script src="https://cdn.jsdelivr.net/npm/flow-documentation-framework/dist/flow-docs.min.js"></script>

Usage

Option A: Static mode (pre-built JSON)

Generate the JSON from your docs folder:

npx flow-documentation-framework ./my-docs -o flow-docs-data.json

Then include in your page:

<div id="docs" style="height:100vh"></div>
<script src="https://cdn.jsdelivr.net/npm/flow-documentation-framework/dist/flow-docs.min.js"></script>
<script>
  FlowDocs.init({
    container: '#docs',
    dataUrl: './flow-docs-data.json'
  })
</script>

Option B: Dynamic mode (server reads folder live)

Point the framework at a server endpoint that scans your docs folder on each request. No build step needed.

<div id="docs" style="height:100vh"></div>
<script src="https://cdn.jsdelivr.net/npm/flow-documentation-framework/dist/flow-docs.min.js"></script>
<script>
  FlowDocs.init({
    container: '#docs',
    apiUrl: '/FlowDocsHandler.ashx'  // or your endpoint
  })
</script>

Server Adapters

ASP.NET WebForms (.ashx)

Copy servers/FlowDocsHandler.ashx into your project. Edit the DOCS_FOLDER constant:

Private Const DOCS_FOLDER As String = "~/Docs"

The handler exposes two endpoints:

Method	URL	Description
GET	/FlowDocsHandler.ashx	Returns all skills and files as JSON
POST	/FlowDocsHandler.ashx?action=save	Saves a file (body: {skill, file, content})

Node.js / Express

const express = require('express')
const flowDocs = require('flow-documentation-framework/servers/flow-docs-server')

const app = express()
app.use('/api/docs', flowDocs('./my-docs-folder'))
app.listen(3000)

PHP

Copy servers/flow-docs-server.php into your project. Edit $DOCS_FOLDER:

$DOCS_FOLDER = __DIR__ . '/docs';

How It Works

1. One GET request at init loads all documentation into browser memory
2. Navigation, search, TOC — all client-side, zero additional requests
3. Editor save — one POST per save, writes file to disk via the server adapter

Browser                         Server
  │                               │
  │  GET /FlowDocsHandler.ashx    │
  │──────────────────────────────>│  Scans docs folder
  │<──────────────────────────────│  Returns JSON with all files
  │                               │
  │  (navigate, search, TOC)      │
  │  all in-memory, no requests   │
  │                               │
  │  POST ?action=save            │
  │──────────────────────────────>│  Writes file to disk
  │<──────────────────────────────│  {success: true}

Docs Folder Structure

Each skill is a folder containing a SKILL.md entry point:

my-docs/
  getting-started/
    SKILL.md
    examples/
      hello.js
      query.sql
    references/
      guide.md
  api-reference/
    SKILL.md
    examples/
      schema.json

File References

In SKILL.md, link to local files to embed them as code blocks:

## Example

[See the code](examples/hello.js)

This renders the file content inline with syntax highlighting.

Search Flags

Use --flag syntax in the search box to filter results:

Flag	Description
--ejemplo	Code examples (.vb, .js, .html, .cs)
--ref	References folder
--lib	Libraries folder
--style	CSS files
--script	JS files
--sql	SQL files
--doc	Markdown files
--vb	VB.NET files

Priority Zones

Tag sections in any file to prioritize them in flag searches:

<!-- @ejemplo -->

// @ejemplo

' @ejemplo

-- @ejemplo

FlowDocs.init(options)

Option	Type	Description
container	string | Element	CSS selector or DOM element (required)
dataUrl	string	URL to pre-built JSON file
apiUrl	string	URL to server endpoint (dynamic mode)
data	object	Inline data object
onSave	function(skill, filePath, content)	Callback after editor save

Returns a FlowDocsInstance with:

• reload(data?) — reload the viewer, optionally with new data
• loadData(data) — load a new data object
• loadFromUrl(url) — load data from a URL

Development

npm install
npm run build        # builds dist/flow-docs.min.js
npm run build:data   # generates example JSON
npm run dev          # builds both