feat(documentation-directory): add typed markdown directory ingestion with author normalization and test coverage
This commit is contained in:
-140
@@ -1,140 +0,0 @@
|
||||
# gitzone ci_default
|
||||
image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
|
||||
|
||||
cache:
|
||||
paths:
|
||||
- .npmci_cache/
|
||||
key: '$CI_BUILD_STAGE'
|
||||
|
||||
stages:
|
||||
- security
|
||||
- test
|
||||
- release
|
||||
- metadata
|
||||
|
||||
before_script:
|
||||
- npm install -g @shipzone/npmci
|
||||
|
||||
# ====================
|
||||
# security stage
|
||||
# ====================
|
||||
mirror:
|
||||
stage: security
|
||||
script:
|
||||
- npmci git mirror
|
||||
only:
|
||||
- tags
|
||||
tags:
|
||||
- lossless
|
||||
- docker
|
||||
- notpriv
|
||||
|
||||
auditProductionDependencies:
|
||||
image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
|
||||
stage: security
|
||||
script:
|
||||
- npmci npm prepare
|
||||
- npmci command npm install --production --ignore-scripts
|
||||
- npmci command npm config set registry https://registry.npmjs.org
|
||||
- npmci command npm audit --audit-level=high --only=prod --production
|
||||
tags:
|
||||
- docker
|
||||
allow_failure: true
|
||||
|
||||
auditDevDependencies:
|
||||
image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
|
||||
stage: security
|
||||
script:
|
||||
- npmci npm prepare
|
||||
- npmci command npm install --ignore-scripts
|
||||
- npmci command npm config set registry https://registry.npmjs.org
|
||||
- npmci command npm audit --audit-level=high --only=dev
|
||||
tags:
|
||||
- docker
|
||||
allow_failure: true
|
||||
|
||||
# ====================
|
||||
# test stage
|
||||
# ====================
|
||||
|
||||
testStable:
|
||||
stage: test
|
||||
script:
|
||||
- npmci npm prepare
|
||||
- npmci node install stable
|
||||
- npmci npm install
|
||||
- npmci npm test
|
||||
coverage: /\d+.?\d+?\%\s*coverage/
|
||||
tags:
|
||||
- docker
|
||||
|
||||
testBuild:
|
||||
stage: test
|
||||
script:
|
||||
- npmci npm prepare
|
||||
- npmci node install stable
|
||||
- npmci npm install
|
||||
- npmci command npm run build
|
||||
coverage: /\d+.?\d+?\%\s*coverage/
|
||||
tags:
|
||||
- docker
|
||||
|
||||
release:
|
||||
stage: release
|
||||
script:
|
||||
- npmci node install stable
|
||||
- npmci npm publish
|
||||
only:
|
||||
- tags
|
||||
tags:
|
||||
- lossless
|
||||
- docker
|
||||
- notpriv
|
||||
|
||||
# ====================
|
||||
# metadata stage
|
||||
# ====================
|
||||
codequality:
|
||||
stage: metadata
|
||||
allow_failure: true
|
||||
only:
|
||||
- tags
|
||||
script:
|
||||
- npmci command npm install -g typescript
|
||||
- npmci npm prepare
|
||||
- npmci npm install
|
||||
tags:
|
||||
- lossless
|
||||
- docker
|
||||
- priv
|
||||
|
||||
trigger:
|
||||
stage: metadata
|
||||
script:
|
||||
- npmci trigger
|
||||
only:
|
||||
- tags
|
||||
tags:
|
||||
- lossless
|
||||
- docker
|
||||
- notpriv
|
||||
|
||||
pages:
|
||||
stage: metadata
|
||||
script:
|
||||
- npmci node install lts
|
||||
- npmci command npm install -g @gitzone/tsdoc
|
||||
- npmci npm prepare
|
||||
- npmci npm install
|
||||
- npmci command tsdoc
|
||||
tags:
|
||||
- lossless
|
||||
- docker
|
||||
- notpriv
|
||||
only:
|
||||
- tags
|
||||
artifacts:
|
||||
expire_in: 1 week
|
||||
paths:
|
||||
- public
|
||||
allow_failure: true
|
||||
@@ -0,0 +1,37 @@
|
||||
{
|
||||
"@ship.zone/szci": {
|
||||
"npmGlobalTools": [],
|
||||
"npmRegistryUrl": "registry.npmjs.org"
|
||||
},
|
||||
"@git.zone/cli": {
|
||||
"projectType": "npm",
|
||||
"module": {
|
||||
"githost": "code.foss.global",
|
||||
"gitscope": "push.rocks",
|
||||
"gitrepo": "smartdocumentation",
|
||||
"shortDescription": "Documentation directory mapping",
|
||||
"description": "A tool for converting git directory structures into navigable documentation sites.",
|
||||
"npmPackagename": "@push.rocks/smartdocumentation",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"documentation",
|
||||
"git",
|
||||
"markdown",
|
||||
"mapping",
|
||||
"sites",
|
||||
"typescript",
|
||||
"development tool"
|
||||
]
|
||||
},
|
||||
"release": {
|
||||
"registries": [
|
||||
"https://verdaccio.lossless.digital",
|
||||
"https://registry.npmjs.org"
|
||||
],
|
||||
"accessLevel": "public"
|
||||
}
|
||||
},
|
||||
"@git.zone/tsdoc": {
|
||||
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.\n\n**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.\n\n### Trademarks\n\nThis 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.\n\nUse 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District Court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
# Changelog
|
||||
|
||||
## 2026-05-02 - 1.1.0 - feat(documentation-directory)
|
||||
add typed markdown directory ingestion with author normalization and test coverage
|
||||
|
||||
- Introduces a new DocumentationDirectory implementation that reads markdown files into typed article objects
|
||||
- Normalizes article metadata from frontmatter, including title fallback behavior and author parsing
|
||||
- Replaces placeholder exports with the actual public API and adds a fixture-based node test
|
||||
- Updates package exports, TypeScript configuration, and dependency versions to support the new implementation
|
||||
- Refreshes project metadata and README to document the documented article ingestion workflow
|
||||
|
||||
## 2024-05-29 - 1.0.2 - maintenance
|
||||
Maintenance and project metadata updates across the 1.0.2 release line.
|
||||
|
||||
- Updated project description
|
||||
- Updated TypeScript configuration
|
||||
- Updated npm metadata for git host configuration
|
||||
- Switched to the new organization scheme
|
||||
|
||||
## 2022-06-10 - 1.0.1 - core
|
||||
Core maintenance update.
|
||||
|
||||
- Fixed core update issue
|
||||
@@ -1,4 +1,4 @@
|
||||
Copyright (c) 2022 Lossless GmbH (hello@lossless.com)
|
||||
Copyright (c) 2022 Task Venture Capital GmbH <hello@task.vc>
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
SOFTWARE.
|
||||
|
||||
+16
-9
@@ -1,14 +1,18 @@
|
||||
{
|
||||
"gitzone": {
|
||||
"@ship.zone/szci": {
|
||||
"npmGlobalTools": [],
|
||||
"npmRegistryUrl": "registry.npmjs.org"
|
||||
},
|
||||
"@git.zone/cli": {
|
||||
"projectType": "npm",
|
||||
"module": {
|
||||
"githost": "code.foss.global",
|
||||
"gitscope": "push.rocks",
|
||||
"gitrepo": "smartdocumentation",
|
||||
"shortDescription": "Documentation directory mapping",
|
||||
"description": "A tool for converting git directory structures into navigable documentation sites.",
|
||||
"npmPackagename": "@push.rocks/smartdocumentation",
|
||||
"license": "MIT",
|
||||
"projectDomain": "push.rocks",
|
||||
"keywords": [
|
||||
"documentation",
|
||||
"git",
|
||||
@@ -18,13 +22,16 @@
|
||||
"typescript",
|
||||
"development tool"
|
||||
]
|
||||
},
|
||||
"release": {
|
||||
"registries": [
|
||||
"https://verdaccio.lossless.digital",
|
||||
"https://registry.npmjs.org"
|
||||
],
|
||||
"accessLevel": "public"
|
||||
}
|
||||
},
|
||||
"npmci": {
|
||||
"npmGlobalTools": [],
|
||||
"npmAccessLevel": "public"
|
||||
},
|
||||
"tsdoc": {
|
||||
"legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
|
||||
"@git.zone/tsdoc": {
|
||||
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.\n\n**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.\n\n### Trademarks\n\nThis 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.\n\nUse 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District Court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Generated
-13494
File diff suppressed because it is too large
Load Diff
+17
-14
@@ -3,23 +3,24 @@
|
||||
"version": "1.0.2",
|
||||
"private": false,
|
||||
"description": "A tool for converting git directory structures into navigable documentation sites.",
|
||||
"exports": {
|
||||
".": "./dist_ts/index.js"
|
||||
},
|
||||
"main": "dist_ts/index.js",
|
||||
"typings": "dist_ts/index.d.ts",
|
||||
"type": "module",
|
||||
"author": "Lossless GmbH",
|
||||
"author": "Task Venture Capital GmbH <hello@task.vc>",
|
||||
"license": "MIT",
|
||||
"scripts": {
|
||||
"test": "(tstest test/ --web)",
|
||||
"build": "(tsbuild --web --allowimplicitany)",
|
||||
"buildDocs": "(tsdoc)"
|
||||
"test": "tstest test/",
|
||||
"build": "tsbuild --web",
|
||||
"buildDocs": "tsdoc"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@git.zone/tsbuild": "^2.1.25",
|
||||
"@git.zone/tsbundle": "^2.0.5",
|
||||
"@git.zone/tsdoc": "^1.1.10",
|
||||
"@git.zone/tstest": "^1.0.44",
|
||||
"@push.rocks/tapbundle": "^5.0.3",
|
||||
"@types/node": "^17.0.41"
|
||||
"@git.zone/tsbuild": "^4.4.0",
|
||||
"@git.zone/tsdoc": "^2.0.3",
|
||||
"@git.zone/tstest": "^3.6.3",
|
||||
"@types/node": "^25.6.0"
|
||||
},
|
||||
"browserslist": [
|
||||
"last 1 chrome versions"
|
||||
@@ -33,13 +34,15 @@
|
||||
"dist_ts_web/**/*",
|
||||
"assets/**/*",
|
||||
"cli.js",
|
||||
".smartconfig.json",
|
||||
"license",
|
||||
"npmextra.json",
|
||||
"readme.md"
|
||||
],
|
||||
"dependencies": {
|
||||
"@push.rocks/smartfile": "^10.0.2",
|
||||
"@push.rocks/smartmarkdown": "^3.0.0",
|
||||
"@tsclass/tsclass": "^4.0.3"
|
||||
"@push.rocks/smartfile": "^13.1.3",
|
||||
"@push.rocks/smartmarkdown": "^3.1.0",
|
||||
"@tsclass/tsclass": "^9.5.1"
|
||||
},
|
||||
"keywords": [
|
||||
"documentation",
|
||||
@@ -55,4 +58,4 @@
|
||||
"type": "git",
|
||||
"url": "https://code.foss.global/push.rocks/smartdocumentation.git"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Generated
+7585
-4103
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
|
||||
Vendored
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Fixture Article
|
||||
author:
|
||||
firstName: Jane
|
||||
surName: Doe
|
||||
birthday:
|
||||
day: 1
|
||||
month: 1
|
||||
year: 1990
|
||||
articles: []
|
||||
---
|
||||
|
||||
# Fixture Article
|
||||
|
||||
This fixture verifies that smartdocumentation turns markdown files into typed articles.
|
||||
@@ -0,0 +1,16 @@
|
||||
import { expect, tap } from '@git.zone/tstest/tapbundle';
|
||||
import * as smartdocumentation from '../ts/index.js';
|
||||
|
||||
tap.test('should read markdown files from a documentation directory', async () => {
|
||||
const documentationDirectory = new smartdocumentation.DocumentationDirectory({
|
||||
pathArg: './test/fixtures/docs',
|
||||
});
|
||||
await documentationDirectory.readDirectory();
|
||||
|
||||
expect(documentationDirectory.articles.length).toEqual(1);
|
||||
expect(documentationDirectory.articles[0].title).toEqual('Fixture Article');
|
||||
expect(documentationDirectory.articles[0].author.firstName).toEqual('Jane');
|
||||
expect(documentationDirectory.articles[0].tags[0]).toEqual('path:article.md');
|
||||
});
|
||||
|
||||
export default tap.start();
|
||||
@@ -1,8 +0,0 @@
|
||||
import { expect, expectAsync, tap } from '@pushrocks/tapbundle';
|
||||
import * as smartdocumentation from '../ts/index.js';
|
||||
|
||||
tap.test('first test', async () => {
|
||||
console.log(smartdocumentation);
|
||||
});
|
||||
|
||||
tap.start();
|
||||
@@ -1,8 +1,8 @@
|
||||
/**
|
||||
* autocreated commitinfo by @pushrocks/commitinfo
|
||||
* autocreated commitinfo by @push.rocks/commitinfo
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@pushrocks/smartdocumentation',
|
||||
version: '1.0.2',
|
||||
description: 'a tool for mapping git directories to documentation sites'
|
||||
name: '@push.rocks/smartdocumentation',
|
||||
version: '1.1.0',
|
||||
description: 'A tool for converting git directory structures into navigable documentation sites.'
|
||||
}
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
import * as plugins from './plugins.js';
|
||||
|
||||
export interface IDocumentationDirectoryConstructorOptions {
|
||||
pathArg: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* a documentation directory maps to a directory with markdown documents
|
||||
*/
|
||||
export class DocumentationDirectory {
|
||||
public options: IDocumentationDirectoryConstructorOptions;
|
||||
public smartmarkdownInstance = new plugins.smartmarkdown.SmartMarkdown();
|
||||
public articles: plugins.tsclass.content.IArticle[] = [];
|
||||
|
||||
constructor(optionsArg: IDocumentationDirectoryConstructorOptions) {
|
||||
this.options = optionsArg;
|
||||
}
|
||||
|
||||
/**
|
||||
* reads a directory
|
||||
*/
|
||||
public async readDirectory() {
|
||||
const smartfileFactory = plugins.smartfile.SmartFileFactory.nodeFs();
|
||||
const virtualDirectory = await smartfileFactory.virtualDirectoryFromPath(this.options.pathArg);
|
||||
const fileTreeComplete = virtualDirectory.listFiles();
|
||||
const articles: plugins.tsclass.content.IArticle[] = [];
|
||||
for (const markdownFile of fileTreeComplete.filter(
|
||||
(fileArg) => fileArg.parsedPath.ext === '.md'
|
||||
)) {
|
||||
const parsedMarkdown = await this.smartmarkdownInstance.getMdParsedResultFromMarkdown(
|
||||
markdownFile.contents.toString()
|
||||
);
|
||||
const frontmatterTitle = parsedMarkdown.frontmatterData.title;
|
||||
articles.push({
|
||||
title: typeof frontmatterTitle === 'string' ? frontmatterTitle : markdownFile.parsedPath.name,
|
||||
author: this.normalizeAuthor(parsedMarkdown.frontmatterData.author),
|
||||
content: parsedMarkdown.originalString,
|
||||
timestamp: Date.now(),
|
||||
tags: [`path:${markdownFile.path}`],
|
||||
});
|
||||
}
|
||||
this.articles = articles;
|
||||
}
|
||||
|
||||
private normalizeAuthor(authorArg: unknown): plugins.tsclass.content.IAuthor {
|
||||
if (typeof authorArg === 'object' && authorArg !== null) {
|
||||
const authorCandidate = authorArg as Partial<plugins.tsclass.content.IAuthor>;
|
||||
if (
|
||||
typeof authorCandidate.firstName === 'string' &&
|
||||
typeof authorCandidate.surName === 'string' &&
|
||||
authorCandidate.birthday &&
|
||||
typeof authorCandidate.birthday.day === 'number' &&
|
||||
typeof authorCandidate.birthday.month === 'number' &&
|
||||
typeof authorCandidate.birthday.year === 'number'
|
||||
) {
|
||||
return {
|
||||
firstName: authorCandidate.firstName,
|
||||
surName: authorCandidate.surName,
|
||||
birthday: authorCandidate.birthday,
|
||||
articles: Array.isArray(authorCandidate.articles) ? authorCandidate.articles : [],
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof authorArg === 'string' && authorArg.trim()) {
|
||||
const [firstName, ...surNameParts] = authorArg.trim().split(/\s+/);
|
||||
return {
|
||||
firstName,
|
||||
surName: surNameParts.join(' '),
|
||||
birthday: {
|
||||
day: 1,
|
||||
month: 1,
|
||||
year: 1970,
|
||||
},
|
||||
articles: [],
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
firstName: 'Unknown',
|
||||
surName: 'Author',
|
||||
birthday: {
|
||||
day: 1,
|
||||
month: 1,
|
||||
year: 1970,
|
||||
},
|
||||
articles: [],
|
||||
};
|
||||
}
|
||||
|
||||
public sendAsDocumentationSet(nameArg: string, targetArg: string): void {
|
||||
void nameArg;
|
||||
void targetArg;
|
||||
|
||||
}
|
||||
|
||||
public async processDirectoryForMkdocs() {}
|
||||
}
|
||||
+1
-3
@@ -1,3 +1 @@
|
||||
import * as plugins from './smartdocumentation.plugins.js';
|
||||
|
||||
export let demoExport = 'Hi there! :) This is an exported string';
|
||||
export * from './classes.documentationdirectory.js';
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
import * as tsclass from '@tsclass/tsclass';
|
||||
import * as smartfile from '@push.rocks/smartfile';
|
||||
import * as smartmarkdown from '@push.rocks/smartmarkdown';
|
||||
|
||||
export {
|
||||
tsclass,
|
||||
smartfile,
|
||||
smartmarkdown,
|
||||
};
|
||||
@@ -1,48 +0,0 @@
|
||||
import * as plugins from './smartdocumentation.plugins.js';
|
||||
|
||||
export interface IDocumentationDirectoryConstructorOptions {
|
||||
pathArg: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* a documentation directory maps to a directory with markdown documents
|
||||
*/
|
||||
export class DocumentationDirectory {
|
||||
public options: IDocumentationDirectoryConstructorOptions;
|
||||
public smartmarkdownInstance = new plugins.smartmarkdown.SmartMarkdown();
|
||||
public articles: plugins.tsclass.content.IArticle[];
|
||||
|
||||
constructor(optionsArg: IDocumentationDirectoryConstructorOptions) {
|
||||
this.options = optionsArg;
|
||||
}
|
||||
|
||||
/**
|
||||
* reads a directory
|
||||
*/
|
||||
public async readDirectory() {
|
||||
const fileTreeComplete = await plugins.smartfile.fs.fileTreeToObject(
|
||||
this.options.pathArg,
|
||||
'**/*'
|
||||
);
|
||||
const articles: plugins.tsclass.content.IArticle[] = [];
|
||||
for (const markdownFile of fileTreeComplete.filter(
|
||||
(fileArg) => fileArg.parsedPath.ext === '.md'
|
||||
)) {
|
||||
const parsedMarkdown = await this.smartmarkdownInstance.getMdParsedResultFromMarkdown(markdownFile.contents.toString())
|
||||
articles.push({
|
||||
title: parsedMarkdown.title,
|
||||
author: parsedMarkdown.frontmatterData.author,
|
||||
content: parsedMarkdown.originalString,
|
||||
timestamp: Date.now(),
|
||||
tags: [
|
||||
`path:${markdownFile.path}`,
|
||||
],
|
||||
});
|
||||
}
|
||||
this.articles = articles;
|
||||
}
|
||||
|
||||
sendAsDocumentationSet(nameArg: string, targetArg: string) {
|
||||
|
||||
}
|
||||
}
|
||||
@@ -1,9 +0,0 @@
|
||||
import * as tsclass from '@tsclass/tsclass';
|
||||
import * as smartfile from '@pushrocks/smartfile';
|
||||
import * as smartmarkdown from '@pushrocks/smartmarkdown';
|
||||
|
||||
export {
|
||||
tsclass,
|
||||
smartfile,
|
||||
smartmarkdown,
|
||||
}
|
||||
+3
-1
@@ -5,8 +5,10 @@
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"noImplicitAny": true,
|
||||
"esModuleInterop": true,
|
||||
"verbatimModuleSyntax": true
|
||||
"verbatimModuleSyntax": true,
|
||||
"types": ["node"]
|
||||
},
|
||||
"exclude": [
|
||||
"dist_*/**/*.d.ts"
|
||||
|
||||
Reference in New Issue
Block a user