Compare commits
9 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jkunz
|
fee4630273 | ||
|
jkunz
|
58c786cbec | ||
 philkunz
|
179ccd3883 | ||
|
philkunz
|
e703b918d7 | ||
|
philkunz
|
d1b476846d | ||
|
philkunz
|
7cc6cf2d10 | ||
|
philkunz
|
757361cce8 | ||
|
philkunz
|
ad344c6659 | ||
|
philkunz
|
70daab81e4 |
-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
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
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
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
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
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
SOFTWARE.
|
SOFTWARE.
|
||||||
|
|||||||
+29
-10
@@ -1,18 +1,37 @@
|
|||||||
{
|
{
|
||||||
"gitzone": {
|
"@ship.zone/szci": {
|
||||||
|
"npmGlobalTools": [],
|
||||||
|
"npmRegistryUrl": "registry.npmjs.org"
|
||||||
|
},
|
||||||
|
"@git.zone/cli": {
|
||||||
"projectType": "npm",
|
"projectType": "npm",
|
||||||
"module": {
|
"module": {
|
||||||
"githost": "gitlab.com",
|
"githost": "code.foss.global",
|
||||||
"gitscope": "pushrocks",
|
"gitscope": "push.rocks",
|
||||||
"gitrepo": "smartdocumentation",
|
"gitrepo": "smartdocumentation",
|
||||||
"description": "a tool for mapping git directories to documentation sites",
|
"shortDescription": "Documentation directory mapping",
|
||||||
"npmPackagename": "@pushrocks/smartdocumentation",
|
"description": "A tool for converting git directory structures into navigable documentation sites.",
|
||||||
|
"npmPackagename": "@push.rocks/smartdocumentation",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"projectDomain": "push.rocks"
|
"keywords": [
|
||||||
|
"documentation",
|
||||||
|
"git",
|
||||||
|
"markdown",
|
||||||
|
"mapping",
|
||||||
|
"sites",
|
||||||
|
"typescript",
|
||||||
|
"development tool"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"release": {
|
||||||
|
"registries": [
|
||||||
|
"https://verdaccio.lossless.digital",
|
||||||
|
"https://registry.npmjs.org"
|
||||||
|
],
|
||||||
|
"accessLevel": "public"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"npmci": {
|
"@git.zone/tsdoc": {
|
||||||
"npmGlobalTools": [],
|
"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"
|
||||||
"npmAccessLevel": "public"
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Generated
-13494
File diff suppressed because it is too large
Load Diff
+33
-16
@@ -1,25 +1,26 @@
|
|||||||
{
|
{
|
||||||
"name": "@pushrocks/smartdocumentation",
|
"name": "@push.rocks/smartdocumentation",
|
||||||
"version": "1.0.2",
|
"version": "1.1.0",
|
||||||
"private": false,
|
"private": false,
|
||||||
"description": "a tool for mapping git directories to documentation sites",
|
"description": "A tool for converting git directory structures into navigable documentation sites.",
|
||||||
|
"exports": {
|
||||||
|
".": "./dist_ts/index.js"
|
||||||
|
},
|
||||||
"main": "dist_ts/index.js",
|
"main": "dist_ts/index.js",
|
||||||
"typings": "dist_ts/index.d.ts",
|
"typings": "dist_ts/index.d.ts",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"author": "Lossless GmbH",
|
"author": "Task Venture Capital GmbH <hello@task.vc>",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"test": "(tstest test/ --web)",
|
"test": "tstest test/",
|
||||||
"build": "(tsbuild --web --allowimplicitany)",
|
"build": "tsbuild --web",
|
||||||
"buildDocs": "(tsdoc)"
|
"buildDocs": "tsdoc"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@gitzone/tsbuild": "^2.1.25",
|
"@git.zone/tsbuild": "^4.4.0",
|
||||||
"@gitzone/tsbundle": "^2.0.5",
|
"@git.zone/tsdoc": "^2.0.3",
|
||||||
"@gitzone/tsdoc": "^1.1.10",
|
"@git.zone/tstest": "^3.6.3",
|
||||||
"@gitzone/tstest": "^1.0.44",
|
"@types/node": "^25.6.0"
|
||||||
"@pushrocks/tapbundle": "^5.0.3",
|
|
||||||
"@types/node": "^17.0.41"
|
|
||||||
},
|
},
|
||||||
"browserslist": [
|
"browserslist": [
|
||||||
"last 1 chrome versions"
|
"last 1 chrome versions"
|
||||||
@@ -33,12 +34,28 @@
|
|||||||
"dist_ts_web/**/*",
|
"dist_ts_web/**/*",
|
||||||
"assets/**/*",
|
"assets/**/*",
|
||||||
"cli.js",
|
"cli.js",
|
||||||
|
".smartconfig.json",
|
||||||
|
"license",
|
||||||
"npmextra.json",
|
"npmextra.json",
|
||||||
"readme.md"
|
"readme.md"
|
||||||
],
|
],
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@pushrocks/smartfile": "^10.0.2",
|
"@push.rocks/smartfile": "^13.1.3",
|
||||||
"@pushrocks/smartmarkdown": "^3.0.0",
|
"@push.rocks/smartmarkdown": "^3.1.0",
|
||||||
"@tsclass/tsclass": "^4.0.3"
|
"@tsclass/tsclass": "^9.5.1"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"documentation",
|
||||||
|
"git",
|
||||||
|
"markdown",
|
||||||
|
"mapping",
|
||||||
|
"sites",
|
||||||
|
"typescript",
|
||||||
|
"development tool"
|
||||||
|
],
|
||||||
|
"homepage": "https://code.foss.global/push.rocks/smartdocumentation",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://code.foss.global/push.rocks/smartdocumentation.git"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Generated
+8176
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1 @@
|
|||||||
|
|
||||||
@@ -1,39 +1,161 @@
|
|||||||
# @pushrocks/smartdocumentation
|
# @push.rocks/smartdocumentation
|
||||||
a tool for mapping git directories to documentation sites
|
|
||||||
|
|
||||||
## Availabililty and Links
|
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.
|
||||||
* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smartdocumentation)
|
|
||||||
* [gitlab.com (source)](https://gitlab.com/pushrocks/smartdocumentation)
|
|
||||||
* [github.com (source mirror)](https://github.com/pushrocks/smartdocumentation)
|
|
||||||
* [docs (typedoc)](https://pushrocks.gitlab.io/smartdocumentation/)
|
|
||||||
|
|
||||||
## Status for master
|
## Issue Reporting and Security
|
||||||
|
|
||||||
Status Category | Status Badge
|
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.
|
||||||
-- | --
|
|
||||||
GitLab Pipelines | [](https://lossless.cloud)
|
## What It Does
|
||||||
GitLab Pipline Test Coverage | [](https://lossless.cloud)
|
|
||||||
npm | [](https://lossless.cloud)
|
`smartdocumentation` reads Markdown files from a documentation directory and converts every `.md` file into a `@tsclass/tsclass` `IArticle` object.
|
||||||
Snyk | [](https://lossless.cloud)
|
|
||||||
TypeScript Support | [](https://lossless.cloud)
|
Each article includes:
|
||||||
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
|
|
||||||
Code Style | [](https://lossless.cloud)
|
- `title`: from frontmatter `title`, falling back to the Markdown filename
|
||||||
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
- `author`: normalized from frontmatter `author`
|
||||||
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
- `content`: the original Markdown source
|
||||||
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
- `timestamp`: generated when the directory is read
|
||||||
Platform support | [](https://lossless.cloud) [](https://lossless.cloud)
|
- `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
|
## Usage
|
||||||
|
|
||||||
Use TypeScript for best in class intellisense
|
```ts
|
||||||
|
import { DocumentationDirectory } from '@push.rocks/smartdocumentation';
|
||||||
|
|
||||||
## Contribution
|
const documentationDirectory = new DocumentationDirectory({
|
||||||
|
pathArg: './docs',
|
||||||
|
});
|
||||||
|
|
||||||
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
|
await documentationDirectory.readDirectory();
|
||||||
|
|
||||||
For further information read the linked docs at the top of this readme.
|
for (const article of documentationDirectory.articles) {
|
||||||
|
console.log(article.title);
|
||||||
|
console.log(article.tags);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
|
## Markdown Frontmatter
|
||||||
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
|
|
||||||
|
|
||||||
[](https://maintainedby.lossless.com)
|
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.
|
||||||
|
|||||||
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 = {
|
export const commitinfo = {
|
||||||
name: '@pushrocks/smartdocumentation',
|
name: '@push.rocks/smartdocumentation',
|
||||||
version: '1.0.2',
|
version: '1.1.0',
|
||||||
description: 'a tool for mapping git directories to documentation sites'
|
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 * from './classes.documentationdirectory.js';
|
||||||
|
|
||||||
export let demoExport = 'Hi there! :) This is an exported string';
|
|
||||||
|
|||||||
@@ -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,
|
|
||||||
}
|
|
||||||
+10
-3
@@ -3,7 +3,14 @@
|
|||||||
"experimentalDecorators": true,
|
"experimentalDecorators": true,
|
||||||
"useDefineForClassFields": false,
|
"useDefineForClassFields": false,
|
||||||
"target": "ES2022",
|
"target": "ES2022",
|
||||||
"module": "ES2022",
|
"module": "NodeNext",
|
||||||
"moduleResolution": "nodenext"
|
"moduleResolution": "NodeNext",
|
||||||
}
|
"noImplicitAny": true,
|
||||||
|
"esModuleInterop": true,
|
||||||
|
"verbatimModuleSyntax": true,
|
||||||
|
"types": ["node"]
|
||||||
|
},
|
||||||
|
"exclude": [
|
||||||
|
"dist_*/**/*.d.ts"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user