docs

Utility for extracting documentation from markdown files and inline comments in source code.

docs.ts is intended to be run directly using bun. You can transpile it to javascript if you want to run it using node.

This is used by the doc-browser component to build searchable, navigable documentation from your project's source files.

Usage

import { extractDocs } from 'docs'

extractDocs({
  paths: ['src', 'README.md'],
  ignore: ['node_modules', 'dist', 'build']
  path: 'public/docs.json'
})

API

extractDocs(options)

Scans directories for markdown files and source code comments.

Options:

• paths: Array of directory paths or file paths to scan
• ignore: Array of directory names to ignore (default: ['node_modules', 'dist'])
• output: if provided, path to write json result.

Returns: Array of Doc objects

Doc object structure

{
  text: string,        // Markdown content
  title: string,       // First heading or filename
  filename: string,    // Just the filename
  path: string,        // Full file path
  pin?: 'top' | 'bottom'  // Optional pinning for sort order
}

Documentation Format

Markdown files

Any .md file will be included in its entirety.

Source code comments

Multi-line comments that start with /*# will be extracted as markdown:

/*#
# My Component

This is documentation for my component.

```html
<my-component></my-component>
```
```js
console.log('hello world')
```
```css
my-componet {
  color: blue
}
```
*‎/

export class MyComponent extends Component {
  // implementation
}
...

The doc-browser will render the output as a test-bed project with documentation and live examples.

Metadata

You can include JSON metadata in comments to control sorting:

html:

ts, js, css: /*{ "pin": "bottom" }*‎/

This will pin the document to the top or bottom of the navigation list.

...