bitovi / bitovi/documentjs

Custom tags | no way to require built-in helpers for use

Open
#226 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
598
Forks
371
PR merge metrics
No merged PRs in 30d

Description

There's a `tags` option on siteConfig objects to load custom defined tags from a doc project's own folders.

Loading custom tags is set-up in such a way that it is impossible to require and use the common built-in helper functions such as `lib/tags/helpers/tagNameDescription` without nasty workarounds.

Currently, I've resorted to creating a `librequire.js` module that crawls back up the stack of parent modules until it finds a module originating from a `/node_modules/documentjs/` folder and then it uses its fully resolved filename to pull up relative references.

i.e.

``` js
// librequire.js
var parent = module;

while ( parent && !/[\\\/]node_modules[\\\/]documentjs[\\/]/.test( parent.filename )) {
parent = parent.parent;
}

parent = /^(.*[\\\/]node_modules[\\\/]documentjs[\\\/]).*/.exec( parent.filename )[ 1 ];

module.exports = function( path ) {
return require( parent + path );
}
```

``` js
// customtag.js
var
librequire = require( "./librequire" ),
typer = librequire( "./lib/tags/helpers/typer" ),
tree = librequire( "./lib/tags/helpers/tree" ),
namer = librequire( "./lib/tags/helpers/namer" ),
tnd = librequire( "./lib/tags/helpers/typeNameDescription" );
```

This is not something you want to burden your framework users with, is it?

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by tracing how the `tags` option loads custom tags, then inspect the built-in helpers under `lib/tags/helpers/` and the `customtag.js`/`librequire.js` workaround shown in the issue. Done means a project-defined custom tag can require and use those helpers without crawling parent modules or resolving DocumentJS paths manually.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.