smartdocumentation/readme.md

# @push.rocks/smartdocumentation

Turn a folder of Markdown files into typed documentation articles. `@push.rocks/smartdocumentation` is a small TypeScript utility for projects that keep their docs in git and want to map those files into structured content that can be rendered, indexed, synced, or published by another system.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## What It Does

`smartdocumentation` reads Markdown files from a documentation directory and converts every `.md` file into a `@tsclass/tsclass` `IArticle` object.

Each article includes:

- `title`: from frontmatter `title`, falling back to the Markdown filename
- `author`: normalized from frontmatter `author`
- `content`: the original Markdown source
- `timestamp`: generated when the directory is read
- `tags`: includes the source path as `path:<relative-file-path>`

It is intentionally focused on the ingestion layer. You can feed the resulting article list into your own documentation site, search index, static-site generator, CMS bridge, or publishing workflow.

## Install

```bash
pnpm add @push.rocks/smartdocumentation
```

## Usage

```ts
import { DocumentationDirectory } from '@push.rocks/smartdocumentation';

const documentationDirectory = new DocumentationDirectory({
  pathArg: './docs',
});

await documentationDirectory.readDirectory();

for (const article of documentationDirectory.articles) {
  console.log(article.title);
  console.log(article.tags);
}
```

## Markdown Frontmatter

Markdown files can provide article metadata through frontmatter.

```md
---
title: Getting Started
author:
  firstName: Jane
  surName: Doe
  birthday:
    day: 1
    month: 1
    year: 1990
  articles: []
---

# Getting Started

Your documentation content goes here.
```

After `readDirectory()` runs, this file becomes an article with the title `Getting Started`, author data from frontmatter, the original Markdown content, and a tag containing its source path.

## Author Handling

`DocumentationDirectory` accepts flexible author frontmatter:

- A full `IAuthor`-style object is preserved when it contains `firstName`, `surName`, and `birthday` fields.
- A plain string such as `Jane Doe` is split into `firstName: 'Jane'` and `surName: 'Doe'`.
- Missing or incomplete author data falls back to `Unknown Author`.

## API

### `new DocumentationDirectory(options)`

Creates a documentation reader for a directory.

```ts
const docs = new DocumentationDirectory({
  pathArg: './docs',
});
```

Options:

- `pathArg`: path to the directory containing Markdown documentation files

### `documentationDirectory.readDirectory()`

Reads the configured directory, parses all `.md` files, and updates `documentationDirectory.articles`.

```ts
await docs.readDirectory();
console.log(docs.articles);
```

### `documentationDirectory.articles`

The generated article array. It is empty until `readDirectory()` has completed.

```ts
for (const article of docs.articles) {
  console.log(article.title, article.author, article.content);
}
```

## Example: Build A Navigation List

```ts
import { DocumentationDirectory } from '@push.rocks/smartdocumentation';

const docs = new DocumentationDirectory({
  pathArg: './docs',
});

await docs.readDirectory();

const navigation = docs.articles.map((article) => ({
  label: article.title,
  sourcePath: article.tags.find((tag) => tag.startsWith('path:'))?.slice('path:'.length),
}));

console.log(navigation);
```

## When To Use It

Use `@push.rocks/smartdocumentation` when you want to:

- Keep documentation as Markdown inside a git repository
- Convert Markdown files into typed article objects
- Extract frontmatter-driven titles and authors
- Preserve original Markdown content for custom rendering
- Build your own docs pipeline without coupling ingestion to one specific site generator

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.