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/. 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/ 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

pnpm add @push.rocks/smartdocumentation

Usage

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.

---
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.

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.

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

documentationDirectory.articles

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

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

Example: Build A Navigation List

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 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.