push.rocks/smartdocumentation
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(documentation-directory): add typed markdown directory ingestion with author normalization and test coverage

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-02 09:43:51 +00:00
parent 179ccd3883
commit 58c786cbec
19 changed files with 7949 additions and 17889 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+123 -54
View File
@@ -1,92 +1,161 @@
# @push.rocks/smartdocumentation
a tool for mapping git directories to documentation sites
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
To install `@push.rocks/smartdocumentation`, you need to have Node.js and npm installed on your machine. Once you have those, run the following command in your terminal:
```bash
npm install @push.rocks/smartdocumentation --save
pnpm add @push.rocks/smartdocumentation
```
This will add `@push.rocks/smartdocumentation` to your project's dependencies.
## Usage
The `@push.rocks/smartdocumentation` package allows you to map your git directory structures into documentation sites efficiently. It leverages TypeScript and a set of sophisticated tools under the hood such as `@push.rocks/smartfile`, `@push.rocks/smartmarkdown`, and `@tsclass/tsclass` to manage and generate documentation content dynamically.
### Setting Up
First, ensure you are using TypeScript and have it configured in your project. You can include `@push.rocks/smartdocumentation` in your TypeScript file with the following import statement:
```typescript
import { DocumentationDirectory } from '@push.rocks/smartdocumentation';
```
### Creating a Documentation Directory
To use the functionality provided by this package, you need to create an instance of the `DocumentationDirectory`. This instance will represent a specific directory containing Markdown files that you intend to use for documentation.
Here's how you can create a `DocumentationDirectory` instance:
```typescript
```ts
import { DocumentationDirectory } from '@push.rocks/smartdocumentation';
const myDocDir = new DocumentationDirectory({
pathArg: './path/to/your/documentation',
const documentationDirectory = new DocumentationDirectory({
pathArg: './docs',
});
```
Make sure to replace `'./path/to/your/documentation'` with the actual path to your documentation directory.
await documentationDirectory.readDirectory();
### Reading the Directory
After creating an instance of `DocumentationDirectory`, you can read the directory to process the Markdown files within:
```typescript
await myDocDir.readDirectory();
```
This method asynchronously processes each Markdown file, extracting information and preparing them for further actions like sending them as a documentation set or rendering.
### Processing and Utilizing Documentation
Once the directory is read, you have several options on how to use the processed documentation. For illustration, let's assume you want to print the titles of all articles in your console:
```typescript
for (const article of myDocDir.articles) {
for (const article of documentationDirectory.articles) {
console.log(article.title);
console.log(article.tags);
}
```
### Sending Documentation to a Destination
## Markdown Frontmatter
While the base package provides you with the tools to read and process documentation, sending this documentation to a specific target or rendering it into a website would require you to implement or use further tools or methods, tailored to your specific needs.
Markdown files can provide article metadata through frontmatter.
### Example Use Case
```md
---
title: Getting Started
author:
firstName: Jane
surName: Doe
birthday:
day: 1
month: 1
year: 1990
articles: []
---
Imagine you are managing a project documentation stored in Markdown files within a git repository. You want to create a documentation site that reflects the structure and content of these files. With `@push.rocks/smartdocumentation`, you can automate the collection and processing of these files, preparing them for a static site generator or a custom rendering engine to display them online.
# Getting Started
You would start by organizing your Markdown files in a clear directory structure within your project. Then, use `@push.rocks/smartdocumentation` to create instances of `DocumentationDirectory` for each directory you intend to document. After processing these directories, you would extract the necessary metadata, content, and structure to feed into your site generator or rendering engine, automating the documentation site's update process as your project evolves.
Your documentation content goes here.
```
### Conclusion
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.
The `@push.rocks/smartdocumentation` package provides a powerful base for handling the conversion of structured, Markdown-based documentation into a format ready for online presentation. With a little setup and some custom tooling around your specific output needs, it can significantly streamline the documentation process for projects of any size.
## 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 that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
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
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
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.