Custom tags | no way to require built-in helpers for use
- 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